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This document describes the SmartUpdate feature of Netscape Communicator. ^^^^^^^^^^^^ 
Netscape Mission Control Desktop. SmartUpdate technology provides a 

softv/are on a user s machine. Although any software can be Installed using SmartUpdate. SmartUpdate technology 
is Ideally suited for installing Navigator plugnns and Java classes. 
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Chapter 1 
Ov rview 



In this chapter: 

• N/Vhy Use iSmartOpdate Technology? 

• SmartUpdate Technology 

• Where to Go from Here 



communicator so that users are not presented wtth the option of updating, 
software on their users' machines. 



that 



happen. 

NOTE- From the perspective of this underlying technology. AutoOpdate is a ^a^ant of SrinartU^ ^ 
s^' a ^Jc^^n^ of system administratofs. This manual describes SmartUpdate. but everything 
that Is relevant to SmartUpdate is also relevant to AutoUpdate. 

Why Use SmartUpdate Technology? 

Th re are many mechanisms for distributing and instalUng software over the Intemet and oyer Intranets. What is the 

advantage of using SmartUpdate technology? 

The answer depends on who you are and your goals. For example: 

the software. 

. If you're a content developer who needs a plug^nfbr your page to^<>^»«^2^^j;^~^ yiur 
developeis. thereby enfldng more of content developers to use your software. 

SmartUpdate Technology 

SmartUpdate t chndogylev rag s xisting technologies as much as possible. The main techn logies you should b 
familiar with b for using SmartUpdate t chnology are: 



JAR files- JAR (Java archive) is an Intemet standard for cr atlng til aichiv^. A SnrjaitlJpdateJAR W is a 
c mprcSed arctSe. containl'ng flies, security infbmiation about the files, and other "metainformation abou 



about the 
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docum ntation. lon/iuAae To create an installable 

is also th tenguagethatawrtentdev^^ 

For information on using JavaScnpt. seem , classes that provide the special 

• ^^^^ 

. w» ^,.hcon^v^MissionControlDesktop.lncludesJAR1llesforUSlng 

. communicator UP9«-« TJJ^.e'liJJ^ 

SmartUpdate technology to upgrade commu ^„ jar tiles with the digital ID of the gerierator 

. .etscapeSignlngTootTheNe.scapeSlgnlngToo..usedtosign..R«.esw«^ 



of the JAR tile. 



informatl n. see Chapter 7. Reference. 

Wh r to Go from Here 

This manual contains the following Chapters and appendixes: 

. Chapter 2. "A Quick LoolC .^Aware 
Pr vldesaslmpte example fromstartfo1»nish.show.ngeUthe steps youn 

package for SmartUpdate. 

. Chapter 3. "SmartUpdate at Runtime- 

riiocusses bilelly how you can change this. 
Describes the typical user expenence and d«cusses bneny 

. Chapter 4. -WHtIng an InstaUation Scripr .^r «,e OTou only need to read this chapter" f you're 

. Chapter 5. "Packaging Software" 

STat downloads the archive.) 
. Chapter 6. "Initiating a SmartUpdate Instanatton" 



can skim this material.) 

• Chapter 7, "Reference- 
Contains reference information on the special Java classes you use for writing trigger and installation scripts. 

• Appendix A. "Sample Installation Scripr 
Contains an example of a complex Installation script. 

• Appendix B. "End User Problems" 

Describes typical problems end users might encounter using SmartUpdate and what should be done about 
them. 

• Appendix C, "Release Notes" 

Contains information on known problems with SmartUpdate technology. Before you start worWng with 
SmartUpdate technology, l>e sure to read the release notes. 

• Appendix D, The NSDiff Utility" 

contains infonnation on using the NSDIff utiltty. which is used In conjunction with the patch method. 
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Chapter 2 
A Quick Look 

In this chapter: 

• WWte Your Software 

• Write an Installation Script 

• Create a JAR File 

• Write the Trigger Script 

• PubRsh the Trigger Script 

need to read the other chapters of this manual. 
This example prepares a plug-in for SmartUpdate: 

. The name seen by the user ftor the plug-in is "Royal Airways Plug-4n" 

• The version is 32.1 .0. 

. The Client Version Registry name fbrthe package is piugins/royalairways/RoyalPI/. 

The installation places the files rplugin. exe.NPRPl .DLL. and help .htminto the Royalairways 
subdirectory under the piugins folder. 



• 



Writ Your Software 

F tch or Stuffit Deluxe to convert your files to this format. 

Write an Installation Script 

these choices. 

Here's a sample installation script for the Royal Ain^ys plug-in. The functions used In this script are documented In 
Chapter 7, "Reference " 

// Conditional alert, 
function cAlert (message) { 
if (! this. silent) 
alert (message) ; 

) 

// Conditional confirm, 
function cConfirm (message) { 

if (this. silent) 
return true; 

else 

return confirm (message) ; 

1 

// variable indicating whether or not installation should proceed, 
binstall = true; 

// Make sure Java is enabled before doing anything else. 
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I cAlert ,.aav, be enable., to Install..,; 

/ / Make sure installation 

, c^aert (..This Plug-in only ^ns on Win32 platforxn.." , . 

Vou do not app^r lo L''tT"\''^?^ ^'^^ ^'^^li^*^ language. 
^ Install anyway?."; "^^"^ English on this itiachiSe. 

"insLjlM -it:h the installation 

vx' ="eTn:tr:a"i:*s^Sd:dat:"? ^ -^^^^^ -^:5-t 

su = new netscape so^^uSSa^rSfi!"\"'°<^' ^' °> ' 
-Royal Airways PlGg-J^-fr^^^^^^P^^^^^ (this, 

// start the install process 

if (err !- o> 

cAlert ("installation error. Aborting.",; 
else { 

bAbort = false; 

pi^Jis^r^:%sts2S^^^^^^ 

list where t».ey go 
PIFolder, "RoySp?;^Lg2^!i^^-="J^"^^^-"' vi, "^^"gin • exe" , 
bAbort = bAbort || (err ! =0)7 this. force); 

if (! bAbort) { 

err = su.AddSubcon9>onent ("RovalPi mi" 

PIFolder, this.forcer^ ' ^' ^^^^ ^W, 

^ bAbort = bAbort II (err .^o!; 

if (.'bAbort) { 

, ::::^^^?^^"^^>:---- 

if (bAbort) 

J cAlert {"installation error. Aborting."); 

/ / Unless there ws<z a v^^^w^ 

else { 

err = su. Finalizelnstall () ; 
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// Refresh list of available plug-ins 
if (err == 0) 

navigator .plugins. refresh (true) ; 
else if (err == 999) { 

cAlertC'You must reboot to finish this installation."); 

err = 0; 

) 

) 

if ( bAbort I I err 0 ) 

cAlert (" Install encountered errors."); 

) 

Cr ate a JAR File 

After you have written your software and an installation script, package your software, its installation script, and any 
auxiliary files your software needs into a JAR file. 

Before you can create your JAR file, you must have a code-signing certificate. You use this certificate to sign your 
code and to identify yoursetf to the users of your installation. Once you have your code-signir« certificate, you use It 
to package your softv^^re and the installation script Into an archive. You use the Netscape Signing Tool to create a 
signed and InstaUable JAR file. If you have Mission Control Desktop, you can use SmartUpdate Bulkier to create JAR 
files. 

Write the Trigger Script 

Once an installable JAR file has t>een published on the Internet or on your company's intranet or extranet, end us rs 
and content developers can access it either by clicking a link to the SmartUpdate JAR or through a trigger script If 
access is through a trigger script, the script can perfonn various checks to ensure that the conect JAR file is 
downloaded and Installed on the user's machine. 

The following HTML page lets a user cfick a button and run a trigger script that initiates SmartUpdate for the JAR file 
named royalpkg.jar. 

This trigger script perfonns checks that duplicate checks performed in the installation script. Putting the checks In the 
trigger script prevents users fi-om v/asting trne downk>acBng archives they dont need. The installation script double 
checks to prevent instalUng useless or even harmful files In case the user bypassed the tri^er script when he or she 
downloaded the JAR file. 

<HTMI*> 
<HEAD> 
<SCRIPT> 

function downloadNow () { 

if < navigator- javaEnabled ( ) ) { 

trigger = netscape.softupdate .Trigger; 
if { trigger. UpdateEnabledO ) ( 

if {navigator .platform == "Win32") { 

vi = new netscape . softupdate .Versionlnfo < 3^ 2, 1, 0); 
trigger . Condi tionalSoftwareUpdate ( 

" http : / /royalairways / royalpkg . j ar" , 
" plugins/ royalairways/RoyalSW" , 
vi, trigger. DEFAULT^MD DE ) ; 

1 

else alert ("This plug-in only runs on Windows NT/95.") 

) 

else 

alert ("Enable SmartUpdate before running this script."); 

) 

else 
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alert ("Enable Java before running this script."); 

</SCRIPT> 
</HEAD> 

<BODY> 

<Hl>Roval Airways Download Page</Hl> 

<P>Welcomet From this page you can download the Windows 95/NT version of 
our famous plug-in. To do so, sintply click the button. </P> 

<CENTER><PORM METHOD=" Post" > 

<INPUT TyPE=" button" VALUE=" Download Plug-in Now!" 

onClick=" downloadNow ( ) ;"> 
< / FO RM>< / CENTESC> 

</BODY> 
</HTML> 

Publish the Trigger Script 

PubOsh the trigger script written In the last section on your web site. 

Make sure that your web server is configured to serve JAR files with the MIME type application/ j ava-archive. 
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Chapter 3 
SmartUpdate at Runtime 

In this chapter: 

Enabling SmartUpdate 

Initiating SmartUpdate 

Installing the Software 

A SmartUpdate consists of two phases: 

. Initiating the process vi»ith a trigger and locating the archive , . 

. Dov^nloadlng the JAR lite, getting perirtsslon to do the installation, and 1^^^^ 

This Chapter gives an ovenrtew of what happens at runtime for t«th ph^-Jubsequent chapters supply the details 
In ttel^rk mat must be done before a SmartUpdate process can be initiated. 

Enabling SmartUpdate 

By default. Sn^rtUpdate is enabled ^rC--)^- ^ 

s^^<Ks^i.s'i:s^t3Es?e«^^ 

SmartUpdate cannot be used on that computer. 

Having Enable SmartUpdate checked corresponds to the following Bne In the user preferences file: 

user_pref (" autoupdate . enabled" , true) ; 

Initiating SmartUpdate 

script 

The SmartUpdate technology does not P-vlde 'i:!::Sfno lii!^^ ^e STSlTld 

provider to provide this interface. A f ^,**,i^-^e n^^^ to download th 

and installation occurs without user intervention. A mininwl u^r interfac^^^ 

latest WllerApp." ; 
upgrade is appropriate. 

ummately. an HTML page triggeis a SmartUpdate «>"tairjnfl a ^^^^^^^XmiT-^'s^^^^^ 
requests the s ftware or by containing an expUdt Ink to a JAR We. See cnapier o. mraa n» 
lnstallatlon."for details about SmartUpdat techn logy triggers. 

bundl files with an InstallaU n script and security mfbrmaH n. 
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installing the Software 

Once the JAR lite is in the download area, the installation script starts to run. It runs in three phases: 

• Setup 

• Getting permission to Install 

• Installing files and cleaning up the temporary file location 
The following sections descrit^e the three phases. 
Installation Setup 

Your installation script may do some Initial checking before it creates a sof twareUpdate object These checks 
ensure that the environment is appropriate for Installing the JAR file. 

Getting Permission 

Communicator must acquire permission to install software for the first time or to update existing ^oftware. This 
pemiission is given on the basis of a Certificate. If SmartUpdate has previously been used to Install soUware n the 
user's computer that you developed and the user checked the -Remember this decision- ^^J^^^Si^^ InstaUaton, 
the security dialog box witt not appear when the user installs software signed with the same Gertilicate. 

Instairmg and updating software require the ability to write to the usefs hard Pfs®^*^^^®'^^^^ 
and executing an arbitrary executable, A mafictous individual with permission to wnte to the usefs harddnve could 
cause extreme damage. For that reason, the installation script must be signed so the user can venfy the source of 
the' new software. . 

When SmartUpdate Is ghfen a jAr file, It extiacti the installation script from the JAR and runs By (tofautt^^^ 
first thing the user sees is the dialog box shown In Rgure 3:i. This dialog box appears when the installation scnpt^ 
calls the startmstall method. You can post your own diatog box before this diafog box. but you cannot prevent 
this dialog box from appearing. 

Figure 3.1 Security dialog box. 



■ -" Java Secu(ily 





NOTE: The Security dlatog box does not appear If the user previously checked the "Remember IWs 
decision" box so that installatlori permission Is permanently granted. 

The dialog Is part of th standard security Int rfec .It asks th us r for permission t runth InstaOation 
script If the us r grants the Installation scrtpt the necessary privilege, th rest of the Installation scnpt 
runs, if th userd nies perrnisslon, th startlnstall method returns an error cod andth installation 
script continues to run, but it caniKJt write to the usei^ hard cHsk. 

As the software dev toper, It is your responsibility to provid the InstaHation script If appropriate, you can 
use custom HTML and JavaScript windows to add additional user interface. SmartUpdat technology 
provides n w Java classes you can use In a JavaScript installation script to perform y ur installation. If 
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you use these classes, Communicator stores a record of the software in a cross-platforrr^ registry, called 
the CBent Version Registry. For detailed infomnation on what you can put in an installation script, see 
Chapter 5, "Packaging Software." 

Installing the Fil s 

If the user has the "Confirm" SmartUpdat pr ference s t, once permission to install or update software 
has been granted, SmartUpdate immediately replaces the security dialog with the installati n dialog box 
shown in Figure 2JZ The Installation dialog box lists the names of the files that are to be Installed. 

\/Vhen this dialog box first appears, the OK button Is dimmed. When the installation script reaches Its call 
to Finalizeinstall, the OK button becomes active. At this point, the user must cSck OK to proceed. 



Figure 3.2 SmartUpdate infonnation dialog box. 



i^Updale: Ihe Shockwave Direcloi plug-in 



the Shockwave Director plug4n 

This Install wni perfomnthe actions listed below 



Install DACOMMUNICATOR 4.5\PROGRAM\^l«o»n*^P32&SW.DLL 

IftsUII DACOMMUNICATOR 4.5\PROORAM\pluotnAShoalMmPIU9iii.«IJS 

Ifistalt DACOMMUMICATOR 4.5\PROORAM\pltigin^hoclwMvtR«adm«NS.Mm 

lostJll DACOMMUNICATOR 4j5U>ROORAM>piyoln^P32DSW\OIRAPI.DLL 

Instatf DACOMMUNICATOR 4j5\PROG>RAlwMu9ii^P320S^DLJE32.EXE 

InsUU 0:^C0MMUNICAT0R 4j5«>ROORAM>p»uQin^P320SWUML32.DLL 

InsUII O:\COMMUN1CATOR 45\PROORAM\plu9lii^P32DSWlPUiOIN32.DLL 

IftsUll D:\C0MMUNtCATOR 4WRO0'RAM>plu9lirfWIP32DSWVC*M*«WA0CMPR JOJ 

InsUil OACOMMUNICATOR 4.5\PR00RAMypl«9>n^P320SWU(liJASWASTRMJOT 

btfUll DtXCOMMUNICATOR 4,5V»ROORAM\plU9in^P32D»«(WClia*FI«h Aa^/LtOZ 

I 




Once the user grants final permission, SmartUpdate completes the installation by nK>ving the files from the 
teirporary area to their final destinations. 

If the user does not have the "T^equire manual confirmation of each instalP SmartUpdate preference set, 
the dialog box shown in Figure 32 does not appear. Instead, the installation script runs to completion 
without requesting confirmation from the user. 



More About Security 

SmartUpdate technology uses the Netscape security frameworic embodied in object signing to provide 
security for SmartUpdate installations. Because of the high risk associated with writing to an user's hard 
disk, SmartUpdate technology requires you to sign your installable JAR arcWves and way post the 
appropriate security dialog boxes l>efore it writes tiles to their final destinations. For infbrnnation on 
Netscape's object signing capabilities, see Netscape Object Signing. This section gives a brief oven/iew 
of the frannework as it applies to SmartUpdate technology. 

The first step in getting pernr^ssion to Install files Is to decode the JAR file enough to see by whonn tts 
contents have been signed. The sequence of events thereafter depends on whether the site administrator 
has placed special security restrictions on the user's computer. 

• If no special security restrictions have been applied. Communicator displays the standard security 
dialog box including Infonnation about who signed the JAR Installation script and asking the us r for 
pennission to Install the software. If the user says to continue. Communicator starts the actual 
installation. If th user says t stop, the startlns tall method returns an error code to the 
Installation script, which should ex cute any cleanup code that it requir s and xit. Communicator 
then d let s th downtoad d JAR file. 

• The site administrator can use Netscape Mission Control Desktop to place restrictions on the 
software that can be installed by nneans of SmartUpdat on a computer. Th following are the 
g neral choices the site administrator can make regarding software Installation: 
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o Never install any software signed by this entity. Do not display the starKiaid security dialog box. 

o Always install any software signed by this entity and do not <^f^ll^^^^,^^f' ""^'"^ 
box^art the insteillation irrimediately and do not ask the use to confirm the Installation. 

o Never install additional software on this corr^er. Do not display the standard security dialog 
box. 

c Let the user decide what to do in every case. Display the standard se^^ Before 
actually Installing the files, display a list of file names that are going to be installed and asK tne 
user for conllnnation. 

For rrK>re information about Mission Control Desktop, see the C^/i^/^es^/ian^^&^s 

Gu/de, available online at 
http://www.inslght.ne1scape.com. 
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Chapter 4 
Writing an Installation Script 

In this chapter 

What's Been Added for Writing I nstallalion Sciipte 
What Your Installation Script Should Do 
Positioning Sottwfare in the Client Version Registry 
Example Installation Scripts 

YOU need to write a JavaScript installation script to ^"uS?o"'^^ 

single cross-platfbmn script--you do not have ^ wrrte a M^ra^ tchik^^ j ^ tracWrtg v rslons 

the user to unlnstall components that were Instatted through SmartUpdate. 

This Chapter describes how to write an Ir^llatlon sal^r Snjr^pdate. either completely using JavaScript or 
using a minimal JavaScript script and a native executat>le installer. 

Special Note for Java Classes 

this one with an installation script. 

This manual discusses the outer JAR file containing an installation script You must create separately the first JAR 
ITe th^So?t^!S^?Sg?ed Java classes but does not contain an Installabon script. 

You should know two special things about using SmartUpdate to Install signed Java classes: 

What's Been Added for Writing Installation Scripts 

TO help you write an installation script several r«w Java c-^-- ha- ^en a*^^^^ 

netscape . sof tupdate . Versioninf o %"<»,'^-'L^"Pl: J^^^^P^^ with JavaScript and 

Chapter 7. "Reference." Through JavaScnpf s UveConnect feature, these classes can ue useo 

let you: 

• Specify a version for your software 

• Specify dir ctori s on the I cal computer 

• Extract files fr ma JAR file onto th local disk 

• Update the Client Version Registry 



You can, of course, also use the full range of JavaScript to Implement as complex an installation process as you 
need. 



In addition, if you are working on a PC platfomi, you nr^y need to also manipulate . inifiles or the Windows Registry. 
To do so, you can use the netscape . sof tupdate . WinProf ile or netscape . sof tupdate • WinReg classes 
described In Chapter 7, "Reference." 

If you are working on a Mac OS platform, you have full access to the G stalt selectors. 

Finally, the JavaScript navigator object has several properties, such as language, platform, and appVersion, 
that are useful when writing an installation script. For information on the navigator object and Its properties, see 
the Jav&Scffpf Gu/de. For information on new JavaScript properties, see What's Afe^ /n JavaScrfpt f.3. 

What Your Installation Script Should Do 

In general, your installation script should perform the tasks discussed in the following sections. Not all installation 
scripts need to perform all of these tasks, nor do all of them have to be done in the order presented here. 

Your installation script runs In a special context; the sof twareUpdate class can be used only in this context in this 
special context, this contains pointers to the JAR file being installed and to other infomnatlon the Sof twareupdate 
obj ct needs. Your script can always use this to refer to the JavaScript context 

B sil nt if asked to 

Your installation nriay want to communicate with the user by posting dialog boxes or other windows. The trigger script 
written t>y the content provider can request that you not display any information to the user. 

Th cont nl developer indicates this by passing the appropriate parameter to the conditionalsof twareUpdate 
or startsof twareUpdate method of the Trigger object, as described in * Installing Silently.* 

When you write your installation script, the value of this . silent indicates whether or not this request was made in 
the trigger script Your installation script should obey this request. That is, if this . silent Is true, your script should 
not post any dialog boxes or display any other windows. 

NOTE: A silent installation can occur only if the signer of the JAR file has the silentlnstall privilege. 
This privilege can l>e set only using Netscape Mission Control. 

You can us functions such as those that follow to chedc the value of this> silent t>efore posting a message or 
asldng a question: 



V Conditional alert, 
fxmction cAlert (message) { 

if (! this. silent) 
alert (message) ; 

V Conditional confirm, 
function cConfirxr. (message) { 

if (this . silent) 

return true; 
else 

return confirm (message ) ; 



Ml example installation scripts in this manual use these functions. 
V^ ck Error Return Codes 

4any of th methods you use can return error cod s. Your script should always check forth se rrors and handle 
1 mappr priat ty when it encounters one. 

> clde Wh th r It's Possible to Install 

li first thing your installation script should do is check that Java is enabled on th user's con^uter. If It is disabled, 
3t the user know tsy posting an alert and then discontinue the installation. In addition, if the Installation is specific to \ 
•articular computer architectur or browser version, check that as well. 



For example, if this installation script Is specific to \A/lndows 95/NT, you can make these checks with code similar to 
this: 

if ( navigator . j 21 v^Enabled( ) ) { 

if { navigator .platform == "Win32") ) { 
// ... perform actual Installation. . . 
) 

else 

cAlert("This installation only works on Windows 95/NT."); 

else 

cAlert("Java is not enabled; enable it and try again."); 

You must check that Java Is enabled before you can do anything with the Java classes discussed in "Wiafs Been 
Added for Writing Installation Scripts'* on page 26. Your installation script does not need to check whether 
SmartUpdate has been enabled; the script canrust be run if It is disabled. 

Note that a well-written trigger script may have already checked this information. Checking in the trigger script 
ensures that users dont needlessly download JAR files they cant use. However, users may bypass a trigger script 
and directly download a JAR file. In this situation, these checks in the installation script protect against attempting an 
inappropriate installation. 

Cr ate a Software Update Object and a Version Object 

The software update object is your main tool for Installing your software. When you create it the first parameter is 
always the keyword this, indicating the JavaScript context The second Is a name for your package that Is used in 
messages to the user. For example: 

su = new netscape,softupdate.Soft:wareUpdate (this, 
"Royal Airways Plug- in" ) ; 

The version object specifies the version of the software you're installing. For example: 
vi = new netscape - softupdate .Versionlnfo { 3, 2, 1, 0); 
You have to create these objects before you can go any further. 
D t rmine a Location in tlie Client Version Registry 

The next step registers your software In the Cftent Version Registry. You need to be careful wtien you pick your 
software's location In the registry. "Positioning Software In the Cfient Version Registr/' on page 33 discusses the 
things you need to know to choose a good location. 

Start the Installation 

You must call the startlnstall method of your SoftwareUpdate object to start the installation process. This 
method displays the security dialog to the user, providing the option to cancel the Installation. A typical call looks like: 

err = su. startlnstall ("plV^i^s/royalairways/RoyalPI/" , vi, 
netscape i, softupdate .SoftwareUpdate. EinjI/;iNSTALL) ; 

None of the other SoftwareUpdate methods work If you dont start the installation or If the user denies permission 
for the installation. 

This call to startlnstall specifies three things: 

• The location in the Client Version Registry to put information at>out the software. For Infomiation on how to 
appropriately choose a location, "Positioning Software in the Client Version Reglstr/* on page 33. 

• Version infomiation for the software package as a whole. 

• Wheth r to display the progress dialog box during the Installation. 
Sp cify Wh re th Piec s Go 

You may want to install a plug-In In Communicator's plug-ins directory. You can call the SoftwareUpdate object's 
Get Folder m thod to determine the names of some standard directories you might use. For example: 



PiFolder = su-GetFolderr Plugins"); 
J.viPold.r - su.OetPolderC'Jav. Damio»<r); 

Downgrade a Component If Requested , 

\!^^!^ ^[Sj^&^'C^yJZrS^'!^! ? ^ P'^^'-^^'y version of that component 

has a higher veision nuX.TStSe STur tS^S^^^^^^^^^ """" ^ '^^^^"^•y instaKr^on 

conditionalsoftwareupdateor startSof?wa^eu?J^ftr^^^ appropriate parameter to the 

-Downgrading a Package" on page gJ''^^^^°^^^^^«"P«i^te method of the Trigger object, as described in 

When you write your installation scriDt the valiM» of t>,4» * ..■ . ^ 

triger script. Usually, your Installat^^scriprs^^uw'^^^ *th'rr2uS''Sloto JT^* ^ 

Object's Addsubcor^onent method pass this . for^^S^V^^g^^' ^" "^"^ ***** ^oftwareUpdate 

a e^r^X^^^^U^e;:^^^^^ -n If the parage as 

component (such as most DLLs in the^A^^S^ platfom«. it Is usually inadvisable to downgrade a shared 

Execute a Native Executable installer 

I'^J^^'" " ' •««>«"• font do «>ls . you-™ w«n, »» ««« ,n««9,on ..rtp, 

T II th User If Rebooting is Necessary ^ 
Finaliz or Abort the Instaiiation 

>^ follow.,, .««,M,o„ .a„«M, vadatte Mic«« wh«^., .„ error ha. b«», «,cou«««, 

if (bAbort) { 

cAlert (" Installation aborted." ) ; 
^ su . Abortlns tall ( ) ; 

else { 

err = su . Finalizelnstall < ) ; 
if (err ~ 0) 

navigator, plugins.refresh<true) ; 
else if (err ~ 9SB) 

els?^^''''^"'''*" "'"^'^ """^^^ ^^^^^'^ installation."); 
^ CAlert ("Error in installation. Aborted."); 



If an error occurs, call Abortinstall to clean up the disk and remove the progress box. 

If all went well, call Finali zeinstall at the end of the Installation. This enables the Install button In the Install 
Digress dialog and giv s the user a final chance to abort the installation. When the user chcte lnsta« Communicator 
SS!I?»ie filSto mS^p rmanent location and updates the Client Version Registry to reflect the Installaton. 

The call to navigator .plugins . refresh is used only when installing a plug-in; it refreshes CommurJ^tor-s nst 
of avateWe Dluq^ns This is not required, but it is strongly recommended If you are installing a plug-In. Ttiis call 
eSSTu^^atel pages^t^^ use ttiis plugnn. The refresh method finds all instances of the Default plug-In whose 
MIME types are now handled by your plug-in. It then deletes these old instances and creates new instances for the 
updated plug-in. 

If the Finaiizeins tall method returns 999, the Installation changed a file that is currently in use by the pper|tlng 
sj^tem Fot me irStetetion to be completed, the computer must be rebooted. Your installation script might check for 
this return code and display a warning to the user. 

Positioning Software in tiie Client Version Registry 

The Client Version Registry Is a registry provWed by Netscape on all platfomrts. separate from t«;?^"i°!^„'^„'^- 
ThrsVeatetiy is a hier^chi«il description of the software registered (or use with Communicator. \ft*ieny^nga^ 
JstellSon^cript fir SmartUpdate. Sne of the things you must decide is where to place your software within the Cfcent 
Version Registry. 

There are two main considerattons In picking a registry key (that is. positioning software in the registry): 

. Pick a name that is unBkely to also be picked by someone across the worid with a similar idea to yours. OWs Is 

referred to as the name^>ace probtem^ 
• DeckJe whether or not the package youTe installing Is dependent on a partfcular installation of Communicator. 

Nam space Clashes 

The namespace problem is a common one when Installing software. If two different SmartUpdate packag^iwe the 
S^rr^SJ^ame problems occur that are similar to the problems mat occur ^"^ 
vSSSoIS^rSstry key-the applications read data set by each other and misinterpret it as their own. 

The usual solution to this problem is to include your company name as part of your ^^^^^l^^"^^;^'^^^^;!^.^ 
registry encourages this for installing software on a Wndows comp«iter ai»d Sun encourages ^^J^^^^^^''^^^ 
riTrW for Java dasses. The same approach is suitable for posMtonIng software in the Cfient Veision Registry. 

SmartUodate uses the registry data to detemiine when an update is necessary. If ano|»ier »»ctege "S«"9^®«"« 
f^feSySy J^lnstalled before your package, two serious problems may occur. To Illustrate these problems, 
assume the other package has a higher version number than your package: 

. installation of your package might never occur. In the nomwl InstaUatlon mode, the Clent Verston Reglstiy 
wouM beHeve your package was already installed and not reinstall It 

. Altemativelv If your Installation process uses exjrce KODEto force installation because you expect the registry 
S^rnSralolirverslonnuml£rforyourpackage.y^^^^^ 

next time a request came to Install the other package. It wouW be needlessly downloaded and ^ .^^ 

SSu^me CHent Version Registry wouW now beBeve an eartler veislon of that package was on the computer. 

Communicator Dependency 

The other major question you shouW ask yourself Is "If the user had A,^ ^^f^'o^^ o^:^*"^^"^*^; '^^^^ 

a single SmartUpdate of my package Install the software for both copies, or only for the currently running one?" 

The most common case is that your software shouW be installed separately for each version of Communl^oron the 
coJiSSIr. it may rely on features specific to a particular veislon In this case, you shouW use a /afeii^* 

pathname to mark the Installation in the registry as relative to the currently running Communicator. 

In particular, softwar Installed In the plugins dlrectoiy or In the j ava/download dlrectoiy fe tr ated by 
Communicator as relativ to the Communicator version. Therefore. If you Install software In these directon s. you 
shoukl also make Its ntry In the registry be relative. 

If your software is usable by multiple versions of Communicator or is not relevant to Communicator at all. you can use 
an absolute pathname to specify the registry position. 
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• The installation places the files rplugin . exe, nprpi . DLL. and help . ht:m Into the RoyalAirways 
sutxilrectory under th Plugins folder. 

The complete script follows: 

Here's a sannple Installation script for the Royal Airways plug-in: 

// Conditional alert, 
function cAlert (message) { 
if (! this. silent) 
alert (message) ; 

) 

// Conditional confirm, 
function cConfirm (message) { 

if (this. silent) 
return true; 

else 

return confirm (message) ; 

} 

// Variable indicating whether or not installation should proceed, 
binstall = true; 

// Make sure Java is enadaled before doing anything else, 
if ( ! navigator. javaEnaQ:>led() > { 
binstall = false; 

cAlert ("Java must be enabled to install."); 

1 

// Make sure installation is attempted on correct machine architecture, 
else if ( navigator .platform. coirpareTo ("Win32" ) != 0 ) { 
binstall = false; 

CAlert ("This plug-in only runs on Win32 platforms."); 

} 

// Check user-interface language, if appropriate- 
else if ( navigator-languge.coit?>areTo ("en" ) != 0 ) { 

binstall = cConfirm ("This plug-in uses the English language. 
You do not appear to be using English on this machine - 
Install anyway? " ) ; 

1 

// If all conditions look good, proceed with the installation, 
if (binstall) { 

// Create a version object and a software update obiect 

vi = new netscape, softupdate .Versionlnfo (3, 2, 1, 0); 

su = new netscape. softupdate.SoftwareUpdate (this, 
" Royal Airways Plug-ih" ) ; 

// start the install process 

err = su.Startlnstall ("plugins/royalairways/RoyalPI/- ^ vi, 
netscape . sof tupdate - Sof twareUpdate . ruIiL_INSTAIJi) ; 

if (err != 0) 

cAlert ("Installation error. Aborting."); 

else { 

bAbort = false; 

// Find the plug-ins directory on the user's machine 
PIFolder = su • GetFolder (" Plugins" ) ; 

// Install the files. Unpack them and list where they go 

err = su;AddSubcon^>onent ("RoyalPI Executable" , vi, "rplugin.exe", 

PIFolder, " Royal PI/ rplugin . exe" , this . force) ; 
bAbort = bAbort I I (err !=0) ; 



if (IbAbort) { T^TY«I ,r-4 "MPPPT DLL" # 

err = su.AddSutocomponent {" RoyalPI DLL", vx, NPRPI.DI.L , 

PIFolder, "", this.force); 
bAbort = bAbort II (err !=0); 

) 

irr't^^ulAlidSubcon^onentC-RoyalPI Help", vi "help.htm", 

PIFolder, " RoyalPI/help . htm" , this . force) ; 
bAbort = bAbort II (err !=0); 

) 

if (bAbort) ^ir.r,"\- 

cAlert ("Installation error. Aborting. ), 



1 

// unless there was a problem, move files to final location 
// and update the Client Version Registry 

if (bAbort) { aw«»-l-ina "> • 

cAJLert ("installation error. Aborting. ), 

su . Abortlnstall ( ) ; 

1 

else { ^ ,x . 

err = su.Finalizelnstall () , 

// Refresh list of available plug-ins 

if (err = 0) 

navigator -plugins . refresh (true) ; 

^"^^lAlArloTJulV rLoo^ to finish this installation."); 
err = 0; 

) 

) 



if ( bAbort II err != 0 ) ^ 
cAlert ("Install encountered errors. ), 



) 



Installing Signed Java Classes 

TWs season descHbes a simple .avaScHpt installation p«>cedure for 1^^^^^ 
classes. For this example: 

. The name for the set of Java classes is -Royal Java." 

• The version Is 1 .0. 

. The CBent Veision Reglstnr name forthe classes is -va/oownload/royalai^^^ Th.s 

relathJe to the Java Download area of the Communicator installaUon. 
. The installation placesthe JAR fie containing the signed Java classes into the .ava/Downloadfolder. 

The complete script follows: 

no cAlert: (); 

// Ma)ce sure Oava is enabled before doing anything else, 
if ( navigator.javaEnabledO ) I 

// create a version object and a software update object 

Tu : 11: .ava..,. 

^^""^ SLtlnstaiu" jaWdovml^ 
"^:t:cape"soS:pdail . Lf twareupdate . liMITED.INSTALD ; 



if (err == 0) { 

// Find the Java download directory on the user's computer 
JavaFolder = su . Get Folder (" Java Download"); 

// Install the JAR file. Unpack it and list where it goes 
err = su.AddSubcomponent (" Royal Java JAR", vx, "rjc.jar', 
javaFolder, , this, force) ; 

1 

// Unless there was a problem, move the JAR file to its final 
// location and update the Client Version Registry 
if (err != 0) 

su.AbortlnstallO ; 
else { 

su . Finalizelnstall () ; , 
cAlertr Installation complete. You must restart Communicator 
to use the new Java classes."); 

' } 
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Chapt r 5 
Packaging Softwar 

In this chapter: 

creating and Signing a SmartUpdate JAfl File, 
Making the Software Available 

once youVe written an installation script for your software, you need to package it for delivery. This chapter 
introduces the packaging process. 

Creating and Signing a SmartUpdate JAR File 

After you have written the software and Its Installation script, you must package those files and any necessary 
auxiliary flies into a signed JAR file for deBvery. 

A SmartUpdate JAR file is a zip file with additional Information. In general, ttiat infornwition J^V '"•^"^^IT^Jl^fi'^^ 
5, SSon scriS for the contents of the JAR file and may optionally include signatures for digitally signed files so 
that a site administrator or an end user can decide whether to install ttie software. 

Important A SmartUpdate JAR file must comply with several restrictions that do not apply ^oJAR archives 
rJenSal All fl^ In me SmartUpdate JAR file must toe signed. The JAR file /77«y/include an installaton 
SJptthalisSlSlS bT^^^ principal. All other flies can signed by multiple principals, but one of 
those principals must be Vne principal who signed tt>e Installation scnpl. 

Befor you can create an installable JAR archive, you must have a code-slgriing certflcate. ^i?^^**?;* 
Stan vouraSe and to Identify yourself to the users of your installation script The certificate is differertfrom the on 
^dTerSl^For dSi?b onUnmg files and getting a code-signing ^^^^^^^^^^^l^^^^ 
Netscape recommends VnA you give your certificate a stwrt nickname. You might have to type It In and the oeiaun 

names are very k>ng. 

Once you have your code^igning certificate, you use it to package your software and the ^"^"f 
o^wo voii lie the Netscaoe Sianina Tool to create a signed and installable JAR archive. Be sure to use the 
!T5'^;>n^to s^rthe SS^^^^^^ on uSng tt.e signing tool, see S^n^^Soff^ Netscape 

SS^f/Uff Too/ 1. 1. 

IVialcing the Software Available 

You must pubBsh the JAR file to make It available for content developers ami end usejs^You n^y P""'^;; PJ^Jj^ly 
on the Internet or privately on your company's intranet or extranet If your JAR file is small enough, you can even 
attach it to an email message. 

If the software is a Netscape plug-in. you can register tt with Netscape to appear in the Plu^n Finder, '" addition, 
you cl^Sle contert diveto,^ the UF^ for tt>e trigger script so that the content ^^^^f Jfjf ^.^^ '"^^^ J 
UF^-Tn p^aS^mat need tt,e sofSare. Providing the URL for ttie trigger script may ^J^^^^^^^^^ 
developer who want to specify a particular plug-In and not just any plugnn for a partteular MIME type. 

If vou want content providers to use a trigger script in ttieir pages so tt^at users can access your software you need 
to giJeTrtS^f dev^^^^ triggir script mat covers the basics for pitting the correct veision^^^^^^ softwar 

on the Ser-s rrwchlne^ote tt»t content developers may modify your sample scnpt C»i?P^«^^^*fj'"9 1^ ^ 
SiSmi^ate installation.- discusses creating trigger scripts. SmartUpdate for Content Devefopers discusses what a 
content developer needs to at)out trigger scripts. 

The web server on which you publish your JAR files must be configured to serve JAR Hies. That is. configure your 
HTTP server to serve JAR files vwth ttie MIME type application/ java-archive. 

If you want to register a plug-In with Netscape so that tt appears in the Plug-in Find r. follow the Instmctions at 
http : //home . netscape . coro/plugins/plg_prof ile . html 

2.^ 
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Chapter 6 
Initiating a SmartUpdate Installation 



In this chapter: 



• Approaches to Initiating SmartUpdate 

. Whafs Been Added for Writing Trigger Scnpts 

• \A/hat Your Trigger Script Should Do 

• SampleTrigger Scripts 

once an .nsta..ab.e JAR Hie has been PU?>«f^f JT ^1^^^^^^ " 
and content developers can access it by '^y^^^^^l^^^ZT^^X^^ the Sol stuff on tWs page, you 

discover they need software by having a content ^^JJ Jj^^ ^J^^J ° ,„^^ae a script that tests to 

should download the KillerApp software.") In this ^^.^'"ferjij ^f^^^ to verify whether or not It Is 

determine exactly which version of the for the download. 

s!;^cht:f:TyT^fiirr?^^^^^^^ 

SmartUpdate to get the software onto the user's machine, 
srarttJ^ate techSotogy for this purpose, and providing 

Approaches to Initiating SmartUpdate 

This approach provides the most control; It Is strongly recommended for reasons discussed below. 
. Providing an HTML page that contains a JavaScript trigger script. That script contains a direct Bnk to a JAR file. 

-?«eC^^-a^^";^ 
in Appendix B, "End User Problems.") 

• Providing a direct link to a JAR file. 

This approach Is the teast woric for you "'^^^S^S'vl tolfap^^^^^^ 

c ntroL It slili may be appropriate, but y^HJ)^*^^ 'jJ^i'^^I^X^^ Spiain th^ 

^rrStfnrefuSr^^^^^^^^^ 

. Providing another vendor-supplied Hnk (such as a vendor-supplied trigger script) 
This approach puts all the onus on the software dev^opej- provided by the developer may be to a 
trigger script, to another installation page, or even to the companys home page. 

Table 6.1 summarizes some of advantages of using a script and Trigger class instead of one of the other 

approaches. 

TabI 6,1 Appr aches t Inlttattng SmartUpdat 



w witMsii t.wp victim II i9iaMOiUV/i I 



Script using Trigger class | 


Script using direct link 


Direct link to JAR file 


• Can query the Client Version 
Registry to see If this software 

/fha oflknna nr ct riifF^r^nt X/pr^inn^ 
^1116 9airi6 Ul a UllldtsiiL WiOiuiiy 

is already Installed and possibty 
avoid a duplicate installation 


• Can't query the Client Version 
Registry 


• Cant query the Client Version 
Registry 


• Can check other infornnatlon to 
ensure that SmartUpdate can 
proceed successfully on this 
machine CAre Java and 
SmartUpdate enabled?") or to 

fVA/hat OS and language are in 
use?*^ 


• Can check other infomnation 
and change download 
strategy accordingly 


• Cant check anything before 
download 


• Consider redundantly checicng 
Sonne conditions in the 
insiaiiaiion scnpi, in i*c»e uits 
user bypasses your script 


• Consider redundantly 
checking sonie conditions in 
the Installation scriot. in case 
the user bypasses your script 


• All checks must be made by 
the installation script, which 
happens after the JAR fil has 
been downloaded to th 
machine 


• Can request that the installation 
DO siieni vuiai is, inoi ui© u»er 
not see dialog boxes during 
installation) 


• Can*t request a silent 

installation 


• Cant request a silent 
installation 


• Can force installation of an 
earlier version of the software 


• Cant force installation Of an 
earlier version 


• Cant force installation of an 
eariier version 


• JAR files are always 

recognizeu, resutiing in lowd 
end user errors 


• An improperly configured web 
server or oroxv server may 
not recognize a JAR file and 
hence not Install It properly 


• An improperly configured web 
server or proxy server may not 
recognize a JAR file and hence 
not install it property 


• Consider Including a README 
tile in the same directory, just in 
case 

i 
1 


• Conskler including a 
README file In the same 
directory. Just in case 

ii 


• Strongly encouraged to Include 
a README file, becaus the 
user nrtust know what 
conditions are needed to 
successfully install the JAR file 



The rest of this chapter discusses writing a trigger script to Initiate SmartUpdate. Trigger scripts are JavaScript scripts 
that use Java classes to initiate SmartUpdate. 

What's Been Added for Writing Trigger Scripts 

To help you write a trigger script, two new Java classes have been added, netscape . sof tupdate . versioninf o 
arKi netscape . sof tupdate . Trigger. These classes are described in Chapter 7. "Reference." Through 
JavaScripts UveConnnect feature, these classes can be used with JavaScrifA and let you: 

• Ensure that SmartUpdate is enabled on the user's macNne 

• Specify a version for your software 

• Query the Client Version Registry 

• Initiate SmartUpdate using a particular JAR file 

You can, of course, also use the full range of JavaScript to Implement as complex a trigger script as you need. 

in add'rtion, the JavaScript navigator object has sev ral prop rtles that can be useful in triggering a software 
download. Two new properties, language and platform, may be particularly useful. For infomwtlon on th 
navigator object and its properties, see the JavaScript Guide. For infomnation on new JavaScript features, see 
What's New in Jaua^pt i.2. 

What Your Trigg r Script Should Do 

32> 



The contents of vour triaaer script can vary in many ways. This section discusses some of the typical tasks It might 
^ rfo^n No?allXe^f tiste ^^^^ necessarily appropriSe for your situation; conversely, you may have specal needs 
not discussed here. 

Licensing and Registration or Payment 

Pr«.fiiientlv software on the web is Bcensed and may require either registration or payment Such requirernervte do not 
cK whInX ImartU^ate to download and install software. Simply make sure youVe gone through the 
appropriate steps before initiating SmartUpdate. 

Decide Whether It's Possible to Use Snr^artUpdate 

The first thing your script shoukl do is check that Java and SmartUpdate are enabled on ttie "s^f ^ ^cl^^- 'J 
i?the?e dteabled then installation of a JAR file wont woric. because the installaton scnpt inside the JAR file 
^i^ifres £,tlf 2 enableS. I?Xr of these features Is disabled, let the user know and then discontinue the scnpL 
You can make these checks with code similar to this: 

if ( navigator .javaEnakbledO ) { 

if ( netscape.softupdate.Trigger.UpdateEnabledO ) I 

// ... perform rest of triffffer. . . 

1 

^■'■^alert ("SroartiUpdate is not enabled; enable it and t:ry again.") 
) 

^^^alert (" Java is not enabled; enable it and try again.") 

Von must check that Java is enabled before you can do anything with the Java classes discussed in "V^af s Been 
ISSiS for^SirTlig|e?£JSI- on page 48. You must check that SmartUpdate has been enabled before you can 
do anything else wtth those classes. 

Ch cl< Machine and Browser Configuration 

Your scriot may use different JAR files depending on the circumstances of the user's parCailar ^«5>"f • f "j^ 
eJai^TyoTi^ have a different executable for different operating systems ojr you may have a different 
^eJface defending on the language used in the browser. Three properties of the navxgator object may be of 
particular use: 



! lanauaqe 11 The language of the browser client software being used. Usually a two-tetler a>de such as en; 
language I ^^"^ ^ five-character code to Indicate a language sutvtype. such as zh_CN. 



platform i| The machine architecture (such as \Mndows 95/NT or Mac OS PowerPC) for which the running 
i browser was compiled 



appVersionilThe version of the browser software bdng used. 



For example, your script could use code such as the following to (^ck a different JAR file based on machine 
architecture: 

if (navigator, platform == "SunOS 5 -4") 

// Trigger download for Sun 
else if (navigator. platform = "Win32") 

// Trigger download for Pi^indows NT/ 9 5 
else if (navigator- platform = "MacPPC") 

// Trigger download for Mac OS PowerPC 
else alert ("You've got a machine type I don't support.") 

Check If This Software Is Already Installed 

Before downloading a JAR file onto the user's machine, you may want to check to s 

You can thus avoid a duplicate download. If your trigger script does not check for an ewstng ^'^^f " 

iie inltallaSon s^^^^^ will. Therefore, this Is not always absolutely n cessary. However, keep m ^J^t^^ 

Kla^S^ entire JAR file has been downloaded to the ^^'^1^^^^"^ 

ofl^^^^^^^^ user the aggravation of waiting while the archive downtoads. only to be toW Never 

3r 



4 -io ortnr 



n so««a,e, sma«upda,e ma, be ,he onN waVj.^%'-'rr.r2j3!!uS-a'SS^.^^^^ 

™c»ne. »«*« be registered In the Client y.iwnR^iajy.y|^^'J^^^^ SmartUpdate Installabon, you 

your software. 

TO one* the V.,^c„ Realetry to, an Insult ve^lon a«. de.de ^ to td«,.r s™«Update on «^ 
basis, use code sinnilar to the following: 

vi = new netscape. softupdate.versionlnfo(2,0,l,0) ; 
trigger = netscape, sof tupdate.Trxgger ; 

trigger . ConditionalSoftwareUpdateC 

:rx?gi-rrrya?Ss/ryifp?"r trigger .O.^U.T_K.OE> ; 
The condi.ionaisof twareupdate method of the Trigger object taRes 4 arguments: 

. The locaBon of the JAR file to download 

«^ tK* r B*.nt Version Registiy (for information on how you pick a name 

. The version of the software being downloaded 

. A««d««n.,*H.w.-«.er.odo»n»ad,u«%(deeonbedln-.n«a»n,S<,.r«^=nP«..5« 
;3^^Tnr^'^-n«"r«'^^^^^^ 
nnla-e has p«».ous^, been evallable •-«»u. a S^rHW. 

ES^Tru-SSTSii^^fJSTSI^S'S-^^^^ 

Sn»aitUpdate. you need to perform these steps: 

, T.« «. .e. ..he MIME typo -s^aated ^ ^ eo»«r. paoKa^e . afe^., re«.,e.ed ^ Co ^. 

the machine. 

2 N<«chec.,*.seeifth.,e..««lonlnton,».ton.n««C.«*V«=K«R^«.r<i»«.'««"- 
,,.he,.,s>eao,.war.waspr.v.ous,,ns.a.«.«.™8n»,,upda.eands™..updau.nd.o«^ 

can Check tt» versions. * ,. ^..^H,«.rt 

3, ,t,he...hove»tonlo,0,,na.>o„ln.h.C^V«,.onR.*a..V,.h.».»«a,.w...--0-'V'^^^^ 

using SmartUpdate. 

,„ ease, the ec„p. n.«. have app«a,on^ code te test the U«ta,^ .e.lon a«.„s. the ^ on. 
and then proceed with installation if necessary. 
To test these conditions, you can use code similar to the following 

III tT^e/l netscape.softupdate.Trxgger; 
// If some version is already installed on this loachine. . . 
if ( myMiinetype ) { 

, X- ■ i. vav^ r-are of version checking 
// installed by SmartUpdate, let i.t take care o£ v 



if (version != null) { 

return trigger . Conditionals of twareUpdate ( 
"http : //royalairways/royalpkg. jar" ^ 
"/royalairways/royalsw" , 

new netscape. softupdate,VersionInfo(minVersion, 0, 0, 0), 
trigger -DE FAULT_FDDE) ; 

} 

//No SmartUpdate information, so it was installed some other way. 

else { . w 

// Put plug-in specific code for checking the version here. 

) 

) 

//No version of RoyalSW is currently installed on this machine, 

// so start the download 

else 

return trigger - StartSof twareUpdate ( 

"http://royalairways/royalpkg. jar*' , trigger .DEFAULT^MODE) ; 

return false; / 



} 



startDownload (0); //Install any version. 
</SCRIPT> 

Downgrading a Package 

In some circumstances you may want to trtgger the update even if a version the software exists 
veS^numhe^ For example, you may want to revert to an earlier version of a software package i a later version 
ioS no?S your needsTou can accompRsh this by using the startsof twareUpdate m^hod 
conditionaisof twareUpdate method and passing the k>rce^M3DE flag in itslast parameter This flag requests 
that an Installation be allowed to override a more recent version of a component The startsof twareUpdate 
method takes two parameters: 

• The location of the JAR file to download 

• A flag determining whether to download silently and whether to force a downgrade. 
Refer to Its description in the reference for details of tWs method. 

The following script fragment unconditionally triggers installation of version 2.0.1 of the RoyalSW software: 

vi = new netscape . softupdate -Versionlnfo (2, 0^ 1, 0) ; 
trigger = netscape .softupdate- Trigger; 

trigger . StartSof twareUpdate ( 

"http://royalairways/royalp]cg. jar"^ trigger . PORCEJ«)DE) ; 

In the corresponding installation script, for the request to be compfied with all calls to the ^of twareUpdate obje^^^^ 
LdlxScom^nent method must pass this . force as their last argun.ent The this . ^^-^^^^a^^^"^^^^^^^ 
Jalue of thT^oRCE^MDDE flag. For information on writing Installation scripis. see Chapter 4. Wing an Installaton 

Script" 

If you need to use both the force_^kdde flag and the silent_M3DE flag described below, the call to 
StartSof twareUpdate would look as follows: 

trigger . StartSof twareUpdate { 

" http : //royalairways/royalpkg . jar" , 
trigger. F0RCE_MDDE I trigger. SILENT_M3DE) ; 

Installing Silently 

A system administrator using the AutoUpdate feature of Mission Control to automatically "PS^^^J^^J^^^^^^ 

usere- machines may wish the upgrade to happen quietly, without displaying dialog boxes or asking questions of the 

user. You can accompTish this by passing the silent_mode flag in the last parameter to the 

Conditionaisof twareUpdate or StartSof twareUpdate method. 
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If this flag is included, the progress and permission dialog boxes may not appear while the software is being 
downloaded and installed. However, this flag does not suppress the appearance of security dialog boxes. 

A silent installation can occur only if the signer of the JAR file has the silentinstall privilege. This privilege can 
be set only using Netscape Mission Control. 

The following script fragment silently triggers installation of version 2.0.1 of the RoyalS W software, if necessary: 

vi = new netscape . softupdate .Versionlnfo (2, 0, 1, 0) ; 
trigger = netscape, softupdate. Triggers- 
trigger . ConditionalSof twareUpdate' ( 

"http: //royalairways/royalpkg. jar" , " /royalairways/RoyalSW , vi, 

trigger - SILENT_MODE) ; 

For the request to be complied with, the con-esponding installation script must be written accordirgly. The 
siLENTjMODE flag is indicated in the Instanatlon script by the value of this . silent. If this . silent is true, the 
installation script should suppress the display of dialog boxes. 

If you need to use both the silent_mdde flag and the force_mdde flag described in "Downgrading a Package" on 
page 53, the call to startsof twareUpdate would look as follows: 

trigger . StartSof twareUpdate ( 

" http : //royalairways/royalpkg. jar" , 
trigger. FORCE_KDDE | trigger . SILENT^MDDE) ; 

SampleTrigger Scripts 

The rest of this chapter gives simple exannpies of trigger scripts that illustrate some of the possibilllies. 
Simplest Trigger Script 

T initiate an update from JavaScript, the only requirenr^ents are that Java and SmartUpdate be enabled for the 
browser and that you have the URL from v4iich to download the JAR file. The following sample code uses the 
startsof twareUpdate method to unconditionally trigger a download from 

http : //royalairways/royalpkg . j ar. 

if ( navigator .javaEnabledO ) { 

trigger = netscape . softupdate .Trigger; 
if ( trigger.UpdateEnabledO ) 
trigger. Startsof twareUpdate ( 

"http: //royalairways/royalpkg. jar" , trigger .DEFAULT_MODE) ; 

else 

document, write ("Enable SmartUpdate before running this script-"); 

} 

else 

document, write ("Enable Java before running this script."); 

Checking Machine Architecture and language 

This example does the following: 

• Checks to make sure Java and SmartUpdate are enabled 

• Creates a version info object for version 4.0.1 .0 

• Checks the machine architectur (Wlndov^^ 95/98/rMT or Solaris 5.5) and user int rface language (Japanese or 
English) 

• Downloads one of 4 JAR files based on these settings 
The script follows: 



f (navigator .javaEnabledO ) { 

trigger = netscape. softupdate .Trigger ; 
if (trigger.UpdateEnabledO ) { ^ n nx. 

vi = new netscape, softupdate .Versionlnfo (4, 0, 1, 0) . 

// Downloads for Windows 95/NT 

if (navigator, plat form == "Win32") I 

if (navigator. language = " jp" ) // Japanese 
trigger. ConditionalSoftwareUpdate ( 

"http://www.royalairways.com/RoyalWin32JPoar , 

"plugins/royalairways/RoyalSW" , vi, 
trigger.DEFAULT^MObE) ; 

else if (navigator. language ~ "en") // English 
trigger. ConditionalSoftwareUpdate ( 

" http : / /www . royalairways . com/RoyalWin32EN . 3 ar , 
"plugins/royalairways/RoyalSW" , vi, 
trigger. DEFAULT_MDDE) ; 

) 

// Download for Solaris ^ ^„ , , 

else if (navigator. platf orm == "SunOS5. 5 ) { 

if (navigator. language ~ " jp" ) 

trigger. ConditionalSoftwareUpdate ( 

" http : / /www . royalairways . com/RoyalSunJP- jar , 

"plugins/royalairways/RoyalSW*' , vi, 

trigger . DEFAULT^MODE) ; 
else if (navigator. language = "en") 
trigger. ConditionalSoftwareUpdate ( 

^^Y\tt,p:/ /wwvr, royalairways.com/RoyalSunEN.jar , 

"plugins/royalairways/RoyalSW" , vi, 

trigger.DEFAULT_M>DE> ; } 1 ) 

Incremental Updates 

,„ou ^ an ln»«n.n«, update (ft., ^-^^^^^I^ l^'l^^To^'d^'T^S^iX 

to check the veiston number of the prevKMKly >^''''f^^;^''^^S^^JiZ affects oolya snan nuinbec of 

times. 

This sample covers these cases: 

. If the sonware either Isnl installed or a version earlier than 3.0 Is Installed, trigger a complete Installation. 

. If version 3.0.0 or 3.0.1 is Installed, incrementally upgrade to version 3.0.2 
The script follows: 

// creates version objects for versions 3.0.0, 3.0 1 and 3.0.2 
v3 0 = new netscape. softupdate .Versionlnfo (3,0,0,35); 
v3~l = new netscape . softupdate .Versionlnfo (3,0,1,25); 
v3~2 = new netscape. softupdate .Versionlnfo (3,0,2,50); 

// Get the version number for the currently ^^^^^^^^f ^^^^^^^^ , 
installed_version = netscape . sof tupdate.Trxgger.GetVersionlnfo ( 

"plugins/royalairways/RoyalSW" ) ; 

// If the installed version is null (that is, not installed) 
//or less than version 3.0, do a complete install, 
if (installed_version = null I I 

installed version.compareTo (v3_0) < 0 ) 

StartSoftwareUpdate ("http : / /www. royalairways . com/v3_2 . ]ar , 
trigger. DEFAULTJM3DE) ; 



// If the installed version is 3.0, do this update 



anng a :>nnanupaaie insiaiiauon 



else if (installed_yersion.coinpareTo (v3_l) < 0) 

netscape . softupdate .Trigger . ConditionalSoftwareUpdate ( 
"http: //www. royalairways .coni/incremental_v0_to_v2 . jar" , 
"plugins/royalairways/RoyalSW*' , v3_2, trigger .DEFAULT_MDDE) ; 

// If the installed version is 3.1, do this update 
else if (installedjversion. compareTo (v3_2) < 0) 

netscape, softupdate .Trigger . ConditionalSoftwareUpdate ( 
"http: //www. royalairways . coin/increinental_vl_to_y2 . jar" , 
••plugins/royalairways/RoyalSW" , v3_2, trigger . DEFAULT JWDDE) ; 
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Chapter 7 
R fer nee 

This chapter provides reference material for the Java objects that can be used with JavaScript to support. 
SmartUpdate trigger scripts. 

All of the objects are in the netscape . sof tupdate package. The objects are 

• Sof twareUpdate object 

• Trigger object 

• Versioninf o object 

• WinPro file object 

• WinReg object 

For general information on JavaScript, see the JavsScript Guide. For general Information on writing plug-ins, see th 

Pfug-Zn Gufde, 

SoftwareUpdate 

You use this object to manage the downloading and installation of software with the JAR Installation Manager. This 
object and Its methods are used in installation scripts. 

In Package 

netscape • sof tupdate 
Meth d Summary 

SoftwareUpdate Creates a SoftwareUpdate object 

Abortinstall Aborts the downloading and installation of the software. 

AddDirectory Unpacks an entre subdirectory. 

Addsubcornponent Unpacks a Single file. 

Deietecomponent Deletes the specitied file and its entry in the COent Version Registry. 

DeleteFile Deletes the spedfled file. 

DiskspaceAvailable Detem^ines whether the specified amount of disk space is available. 

Execute Extracts a file from the JAR file to a temporary location and schedules It for later execution. 

Finalizeins tall Finalizes the installation of the software. 

Gestalt Retrieves information about the operating environment (Mac OS only) 
GetconiponentFolder Retums an object representing the directory in Vifhlch a component is Installed. 

GetFolder Retums an object representing a directory, for use with the Addsubcoinponent method. 

GetLastError Retums the nwst recent non-zero error code. 
GetwinProf ile Constructs an object for working with a VVindows .Ini file. 
GetwinRegistry Constructs an object for working with the \Mndov\« Registry. 
Patch Applies a set of differences between two versions. 

ResetError Resets a saved en^or code to zero. 

setPackageFolder Sets the default package folder that is saved with the root node, 
startinstall Initiayzes installation for the given software and version, 

uninstall Removes a package that was previous installed by SmartUpdate. 

SoftwareUpdate 

Creates a SoftwareUpdate object 
Syntax 



A An nf\r\r\ a 



erence 



SoftwareUpdate ( 
JSObject env, 

String inUserPackageName) ; 
Parameters 

parameter. 

inuser PackageName A string used In user prompts to name this software. 
Returns 

A new SoftwareUpdate ot)ject. 
Description 

YOU must can the startlnstall method alter you call this constructor. It Is an error to call a«y other 
SoftwareUpdate methods t>ef6re calling startlnstall. 

Example 

U«»«,o«<>..ngcode,oc.ea«aSoftwa.eup..teo.^»K>u...h.«rtnB-Roya.A««.y.8o»««-m^ 

boxes: 

su = new netscape.softupdate.softwareupdatecthis, "Royal Airways Sof tware" ) ; 

Abortlnstall 

Aborts installation of the software; performs cleanup of temporary files. 

Meth dot 

S o f t wa r eUpda te 

Syntax 

int AbortlnstalK) ; 

Parameters 

Non . 

Returns 

An Integer error code. For a list of possit,te values, see "Return Codes" on page 102. 
Example 

use the following code to at>ort or to finalize an Installation, based on a variable you set earlier In your code: 

su = new netscape.softupdate.SoftwareUpdate(this, "Royal Airways Software-,; 



if (bAbort) 

su. Abortlnstall ( ) ; 

else { 

err = su. Finalizelnstall () ; 

AddDirectory 

unpack an en^redlrctorylntoatemporary location a«l enters each nie in thedirectory into the C^^^^ 
Registry. 
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SoftwareUpdate 
Syntax 

public int AddDi rectory ( 
String registryName , 
Versionlnfo version. 
String jarSourcePath/ 
Object localDirSpec, 
String relativeLocalPath, 

Boolean forceUpdate) ; (Communicator 4,05 or later) 

public int AddDirectory ( 

String jarSourcePath) ; (Communicator 4.5 or later) 



public int AddDirectory ( 
String registryNaine, 
String jarSourcePath, 
Object localDirSpec, 
string relativeLocalPath) ; 



(Communicator 4,5 or later) 



public int AddDirectory ( 
string registryNaune, 
string version, 
string jarSoUrcePatih, 
Object localDirSpec, 

String relativeLocalPath); (Communicator 4,5 or later) 

public int AddDirectory ( 
string registryName, 
String version. 
String jarSourcePath, 
Object localDirSpec, 
String relativeLocalPath, 

Boolean forceUpdate); (Communicator 4.5 or later) 
Parameters 

The AddDirectory method has the following parameters: 



rer nee 



registryName The pathname in the Client Version Registry for the root directory of the files that are to be 
installed. 

This parameter can be an absolute pathname (beginning with a /) or a relative pathname, (not 
beginning with a slash). 

An absolute pathname is used as specified. A relative pathname is appended to the registry name 
of the package as specified by the package parameter to the startinstall method. 

If you want the pathname to be relative to the current Communicator installation instead of to the 
package being installed, use the prefix •' =cx»Mt*=/ " as the beginning of the pathname. 

If you want the pathname to be relative to me current user foWer, use the prefix " =user=/" . 

This parameter can also be null, in which case the jarsourcePat:hparameter is used as a 
relative pathname. 

Note that the registry pathname Is not the location of the sollware on the computer; it Is me 
location of information about the software inside the Client Version Registry. For Infonn^on on 
choosing an appropriate registry name, see "Positioning Sothvare in the Cfient Version Registry" 
on page 33. 

version A versioninf o object containing the version nunnber for all Installed files. This parameter can be 

null. In virtwch case the package version from startinstall is used. 
jarsourcePath A string specifying the location of the directory wtthin the JAR file. 

An empty string O causes the creation of a subdirectory node in the registry vtrithout ^ally 
unpacking any files, which may be useful when you are updating a package that contains 
subcomponents that could also be updated separately. When j arsourcePath is an empty string. 

registryName cannot be nuH. 

localDirSpec An object representing a directory. The directory is installed ""^er *te d^e^ onttie w ^ 

computer. You create this object by passing a string representing the directory to the GetFoider 

method. ^ « 

subdir The name of a directory to append to localDirSpec, using V as the path separator regardless of 

the platform. 

If subdir is missing, null, or" the filenames are appended directly to the foWer nawe specified 

by localDirSpec 

f orceupdate If true, replaces an existing file regardless of its version. If false, replaces an existing file only if 
Vne replacement has a higher version number. If f orceupdate is missing, thxs . force is 
assumed. 

In most cases, you should use this . force as the vakje for this parameter. This value reA Jts 
the flag passed to the ConditionalSoftwareUpdate or startSof twareUpdatemettlod of 
the Trigger object. For shared system DL1.S. you may want to expOdtty use false, so that 
shared components are not downgraded for other appBcations. For a fuller discussion, see 
"Downgrade a Component if Requested" on page 31. 

Returns 

An integer error code. For a Bst of possible values, see "Return Codes" on page 102. '^sorr» sit^^^ 
AddD^ec tory may return ottier errors. For example. If ttie error was with regard to the signing of the JAR file. 
AddDirectory returns a security error code. 

Description 

The AddDirectory rrwthod puts ttie files in the specified directory in a temporary location. To ,f " 

omer subcomponente to tiielr final location, call ttie Finalizeinstall method alter youVe successfully added all 
subcomponents. 

The tiles are installed If one of the following conditions is tnje: 

• Ther Is no entry for a file In the Client Version Registry 

• There is an entry in the Client Version Registry 



o the corresponding file has been del ted, or 

c the version information of the version parameter Is higher than that of the current entry in the registry, or 
o the version Information ofthe version parameter or of the current ntiyinth registry Is null 

consequently If your Windows plug-in contains riLEVERSioNinfomiation In the header of Hs^verslon infablo^. b 

AddSubcomponent 

unpacks a single subcomponent Into a temporary location. Queues the subcomponent for addition to the CBent 
Version Registry and installation to Its final destination. 

Meth dof 

S o f t wa r eUpda t e 
Syntax 

pijblic int AddSubcomponent ( 
String registryNaine, 
Versionlnfo version/ 
String jarSourcePath, 
Object localDirSpec, 
String relativeLocalPath/ 

Boolean f orceUpdate) ; (Communicator 4.0 or laterj 

public int AddSubcomponent ( 
String registryName, 
String version. 
String j arSourcePath, 
Object localDirSpec, 
String relativeLocalPath, 

Boolean f orceUpdate) ; (Communicator 4.5 or laterj 

public int AddSubcon^ponent ( 

String jarSourcePath) ; (Communicator 4.5 or laterj 

public int AddSubcon^onent ( 
String registryName, 
String j a rS puree Path, 

Object localDirSpec, 7.^^^, 
String relativeLocalPath) ; (Communicator 4.5 or laterj 

public int AddSubcon^onent ( 
String registryName, 
String version. 
String jarSourcePath, 
Object localDirSpec, 

String relativeLocalPath); (Communicator 4.5 or laterj 
Parameters 

The AddSubcomponent method has the following parameters: 



ence 



registryName 



version 



jarSourcePath 



The pathname in the Client Vereion Registry about the subconriponenL 

This oarameter can be an at}solute pathname, such as «. ,k i ^ 

™y'SJirways/RoyalSW/executableora r lative pathname, such as executable. 

Typically, absolute pathnames are o/7/^used for shared components or corriponenls that 
come from another v ndor. such as /Microsof t/share<J/msvcrt40 . dll. 

TvDicallv relalive pathnaiTies are relative to the main pathname spedfied In th 
IS^instaJl nShod. If you want the pathname to be relative to the current 
Communicator installation instead of to the package being Installed, use the prelfa< 
•• =cx>M4=/".as the beginning of the pathname. 

ifyouwantthe pathname to be relative to the cuaent user folder, use the pretbc- =oser=/- . 

This parameter can also be nuB. in which case the j arSourcePath parameter is used as a 
relative pathname. 

Note that the registry pathname is not the location of the software on the machine: it tettie 
to^ti^nof^JfSSSn about the software inside the Cflent Version Jil'^l''"^^^ 
on cJ.o!islng rappropriate registry name, see "Positioning Software in the Client Version 

A^r'^^oi^Xoyect (Communicator 4.0) or a string (Communicator 4.^ oor^ the 
veSon number for L subcomponent. If a string, the ^<>"^^«/--^-^^ ,t 
This parameter can be null. In this case, no version is associated with this component and It 
is always updated. ,aes«i 
A string spedfj^ng the location of the subcomponent withm the JAR tile. 



localDirSpec 



An obiect reoresenOng a directory. The subcomponent is Installed 

SJeJf^rnf vSTSIate this object by passing a string representing the directory to the 
Get Folder method. 

re^rdless of the convention of the underlying operating system. Ifthls paiameterls blank or 

NULI., jarSourcePath is used, 
forceupdate If true, replaces an existing component 'eoardless of its vereion tffals^ replaces an 

forceupdate ^^^^ component only If the replacement has a higher version number. 

In most cases you shouW use this . force as the value for this paranr»eter. This value 
refl^ ^ted to the ConditionalSof twareUpdate or ^^"^Sof twareUpdate 

r^Sod Of therrigger obiect. For shared system DLLs, you may want to explicitly use 
^rfsl^rat sha^rS components are not downgraded tor other applications. For a full r 
discussion, see "Dowmgrade a Component If Requested" on page 31. 

Returns 

returns a security error. 



The^dsubcon^onent method puts the subcomponent in a temp^aiyj^c^lon ^J^^^ 



Description 

The AddSubcomponent meinoa puu» uic ^^i^s^m^i*^ ''^"^J J w«.,.s,** <^itr^r^^fiAhi added all 

subcWonents to their final tocatlon. call the Finalizeinstali method after youVe successfully added 

sut>component5. 

The component is installed If one of the following conditions is tme: 

• There Is no ntiy for this lile in the Client V rslon Registry 

• There is an entry in the Client Version Registry Ai/f 

o the actual file has been deleted, or 

c the version infom«tion of the version parameter is higherthan that of the current entry in the register, or 



o the version information of the version parameter or of the current entry in the registry Is null 



Windows only: Some Windows execute bles and DLLs have embedded fi levers ion information in the version 
info blocl< of the file resource. If this information is present In />o//?Xhe already installed version of the component and 
the component to be installed now, then the Information in the two files is compared. If the filevers ion Infonnation 
in the prospective new component is equal to or greater than that of the existing component, the new component Is 
installed. Otherwise, it is not. This check is not made if either component doesn't contain filevers ion infonnatlon. 

Consequently, if your NA/lndows plug-in contains filevers ion information in the header of its version info block, be 
sure to increment this value for each release. Note that this Inlbmnation Is four comma-separated Integers In the 
header of the veision information block; It is not the FileVersion string In ttie body of the version information block. 

Examples 

The following examples show different uses of the registryName parameter 

su.Startlnstall (" plugins/RoyalPlug" , version, 

netscape, softupdate .SoftwareUpdate- FULL_INSTALL) ; 

// To create node /netscape /Coinmunica tor #? /plugins/royalplug/npplug 
su. AddSubcoit^onent ("npplug" , . - . ) ; 

// To create node /MS/Shared/Ctl3d. dll 
su.AddSubcon^onent (" /MS/Shared/ctl3d.dir' , . . . ) ; 

// To create node /netscape/ Communicator #? /NetHelp/royalplug/royalhelp •html 
su.AddSubcomponent ("«COMM=/NetHelp/royalplug/royalhelp.html'" ,...); 

D I teComponent 

Deletes the specified file and renrK>ves its entry from the Client Version Registry. 
Meth dot 

S o f t wa r eUpda te 
Syntax 

int DeleteCoinponent 

(String registryName); fCommunlcator 4.5 ojc latejr) 

Parameters 

The Deletecomponent method has the following parameter 

registryName The pathname in the Client Version Registry for the file that Is to be deleted. 



Returns 

An Integer error code. For a fist of possible values, see "Retum Codes" on page 10Z 
Description 



The DeieteCon5>onent method deletes the spectfled file and renwves the file's entry from the CHent Version 
Registry. If the file is currently being used, the name of the file that Is to be deleted is saved and Communicate 
attempte to delete It each time It starts up until the file is successfully deleted. This method is used to delete files max 
cannot be removed by the uninstali method or to remove files that are no longer necessary or v^ose names have 



\ files that 

\ removed by the uninstali method or to remove files that are no longer necessary or vrhose na 

changed. 

D let File 

Deletes the specified fil but does not r move it from the Cli ntV rslon Registry. 
Method of 



Ter nee 



Sof twareUpdate 
Syntax 

int DeleteFile 

(Object folder. 

String relativeFileName) ; (Communicator 4.5 or later) 
Parameters 

Th DeleteFile method has the following parameters: 

localDirSpec An Object representing the directory from which the file is to be deleted. 
relativeLocalPath A pathname relative to localDirSpec representing the file that is to be deleted. 



Returns 

An integer en-or code. For a fist of possible values, see "Return Codes" on page 10Z 



Description 



The DeleteFile method deletes the specified file but does not renrwve the file's entry from the Client Version 
Registry. If the file is currently being used, the name of the file that is to be deleted Is sav^ and <^<>'T^";^"[»]f ^ 
attempts to delete it each time it starts up until the file Is successfully deleted. This method is used to delete files that 
w re not instafied or created by a SmartUpdate process. 



DiskSpaceAvailable 

Gets the amount of space that is available on a d^k. 



Method of 



SoftwareUpdate 



Syntax 

long DiskSpaceAvailable ( 

Object localDirSpec); (Communicator 4.5 or later) 



Parameters 

The DiskSpaceAvailable nr^ethod has the following parameter. 
localDirSpec An object representing a directory obtained by GetFolder. 



Returns 

The number of bytes available on the drive that contains localDirSpec. 
Description 

The Dis kspaceAvailable method gets the amount of disk space that is available on the drive that contains 
localDirSpec Other processes may be using disk space, or your installation process may require more space than 
th installed flies, so a a return value that is equal to the size of your Installed files is not a guarantee that there is 
nough space to perform the installation. 

Execute 

Copies an ex cutablefll from a JAR file to a temporary location and schedules it for later xecuti n. 

M th d f 

S o f t wa r eUpda t e 
Syntax 



int Execute ( 

jarSourcePath) (Coimnunlcator 4.0 or later) 

int Execute ( 

String jarSourcePath, 

String args) ; (Communicator 4.5 or later) 
Parameters 

The Execute method has the following parameters: 
j arSourcePathThe pathname of the file to extract and execute. 

args A parameter string that is passed to the executable. (Ignored on Mac OS) 



Returns 

An integer error code. For a list of possible values, see "Return Codes" on page 102. 
Description 

The Execute method extracts the named tile from the JAR file to a temporary We name. f^^^ 
Finalizeinstaii method to actually execute the file. You could use this method to launch an InstallShleW installer 
stored in a JAR file. 

ExampI 

The following example performs an installation by retrieving and mnning an executable file: 

version = new netscape. softupdate.Versionlnfo (2, 1, 0, 0); 

su = new netscape. softupdate.SoftwareUpdate (this, "Royal Software ); 

su . Startlns tall (" plugins/RoyalSW" , version, 

netscape . sof tupdate . Sof twareUpdate • FULL^IKSTALL) ; 
su,Execute(" royalpkg.exe" ) ; 
su. Finalizeinstaii () ; 

Finalizeinstaii 

Finalizes the installation of the software. Moves ail components ^^eir final tocajons. l^^^ pending 
executions, and registers the package and all of Its subcomponents in the Client Version Registry. 

Method of 

Sof twa r eUpda t e 
Syntax 

iiit Finalizeinstaii ( ) ; 

Parameters 

None. 

Returns 

An integer error code. For a Bst of possible values, see ^Return Codes" on Pf9«J02. Jrj sonje s^a^^^ 

may r^um other errors. For example. If the error was with regard to the signing of the JAR file. It returns a s cunty 

error. In a few cases you nnay get a registry error. 

Example 

Use the following code to abort or to finalize an Installation, based on a variable you set earU r In your code: 
su = new netscape. softupdate.SoftwareUpdate (this, "Royal Airways Software"); 

if (bAbort) 



su . Abortlnstall ( ) ; 
else { 

err = su. Finalizelnstall ( ) ; 

Gestalt 

(Macintosh only) 

Retrieves Information about the operating environment. 
Meth dof 

S o f t wa r eUpda t e 
Syntax 

OSErr Gestalt ( 

String selector, 
long * response) ; 

Parameters 

The Gestalt method takes the following parameters: 
selector The selector code for the information you want. 

response On return, the requested information. The fomiat depends on the select code specified in the selector 
parameter. 

Description 

The Gestalt method Is a vsrrapper tor the Gestalt function of the Macintosh Toolbox. For information on that 
function, see /nskfe Msa'ntosh: Operaffng System Utf/iifes. 

This method returns null on Unix and \A/indows platforms. 

G tComponentFolder 

Returns an object representing the directory In which a component is installed. 

Meth dof 

Sof twareUpdate 

Syntax 

Object GetComponent Folder 

(String registryNciine) (Coininunlcator 4.0 or later) 

Object Ge tComponentFolder { 
String registryName, 

String subDirectory) ; (Communicator 4.5 or laterj 
Parameters 

The GetCoit?)onentFolder method has these parameters: 

regist ryName The pathname In the Client Version Registry for the component whose installation directory is to be 
obtained. 

subDirectoryA String that specifies the name of a subdirectory. If the specified subdlrectoiy doesn't exis^^^^ Is 
created. This ^rameter is available in Communicator 4.6 or later and may be case sensitve 
(depending on the operating system). 

Returns 

An object representing the dir ctoiy In which the component is installed, or null if the component could not be found 
or if subDirectory refers to a file that already exists. 



Description 

The GetcoitiponentFolder method to find the location of a previously installed soltware package. Typically, you 
use this method with the Addsubcomponent method or the AddDirectory method. 

Example 

Use the following code to find the fold r containing th Royal AInrays plug-In: 

su = new netscape. softupdate.SoftwareUpdate (this, "Royal Software"); 
folder = su^GetcbitponentFolder rplugins/RoyalsW") ; 

GetFolder 

Returns an object representing one of Netscape's standard directories. 

Method f 

SoftwareUpdate 

Syntax 

Object GetFolder ( 

String FolderName) ; (Conuaunlcator 4. O or later) 

Object GetFolder ( 

String folderName, 

String subDirectory) ; (Communicator 4,5 or later) 

Object GetFolder ( 

Object localDirSpec, 

String subDirectory); (Communicator 4.5 or later) 
Parameters 

The GetFolder method has the following parameters: 

f olderName A string representing one of Netscape's standard directories. Ttiere are two sets ^If^^^^^^^^^ 
for this parameter. The first set contains piatfomrHndependent locatons; the second set conteins 
platform-specific locations. You are encouraged to use the platfornv4ndependent locations. S the 
fet In the Description section for the two sets of locations. In Communicator 4.5 f oldernaroels not 
case sensitive; in Communicator 4.0, f oldernamemust match a exactly. 

subDirectory A string that specifies the name of a subdirectory. If the spedtied subdlrectoiy ^^^J^"^ ^ 
created. This parameter is available in Communicator 4.5 or later and may be case sensitive 
(depending on the operating system). 

localDirSpec An object representing a directory obtained by Getcoit^onentFolder or GetFolder. This 
parameter Is available in Communicator 4.5 or later. 

Returns 

An object representing one of Netscape's standard directories, or null in case of error or if subDirectory refers to 
a file that already exists. 

Description 

The GetFolder method obtains an object represenOng one of Netscape's standard directories, tor use with the 
Addsubcomponent and GetWinProf ile methods. 

The value of f olderName must be one of the following: 
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PlatforiTMndependent locations PlatforrrHlependent locations 

-Communicator "Mac System" 

"CurrentUser "MacDesktop" 
" Java Download" -MacTrash" 
-Plugins- "Mac Startup" 

-Program" "Mac Shutdown" 

-Netscape Java Bin" "Mac Apple Menu 

-Netscape Java Classes" "Mac Control PaneP 

-Temporary- -Mac Extension" 

-NetH ip" (Communicator 4.6 or latei) "Mac Fonts" 

-OS Drive- (Communicator 4.5 or latef) "Mac Preferences" 

-file7/r (Communicator 4.5 or later) "Unix Locaf 

-User Pick- -UnlxUb- 

-Win System" 
"Win System16" 
-Windows" 

T« value Pick- Is a special case. It you spedfy tt,is -j^^JV^^SSTs' '^^S^S^^i^'^^ 

,„ communica.0, « or later, when -Use, PK*' la ««»ed, always pr»«««. w«h a dlaloa box and 

asked to choose the directory to use. 

The -.lev/r *,nn is .m, va.d when ,he s*pi.ec«.yp..an»..r u.«.. « must be In URL n-nus «,e 
"Ule-V/r part For example, 

mydir = su. GetFolder (" f ile: ///" , " cl/mysof tco/somedir) ; 
Note that forward slashes are used, regardless of the platform. 

♦ort uuith -\AiSn- "Mac" or -Unix" are specific to those platforms. You shouW be careful 

2t?s^s-^.?Se''dr2r:;^,T«Jic^vo'.;^^^^ 

Example 

TO get an Direct representing the standard plug4ns directory, you would use this call: 
plugindir = su. GetFolder (" Plugins" ) ; 

GetLastError 

R^ums the most recent nonzero error code. 

AAethod of 

SoftwareUpdate 

Syntax 

int GetLastError () ; (Communicator 4.5 or later) 

Parameters 

None. 

Returns 

The most recent nonz ro error cod . For a list of possible valu s. see "Return Codes" on page 102. 
D scription 

4P 



AddDirectory until the last Adds ub component or AddDirectory call. 

The GetLastError method does not return errors from methods that return objects, such as GetFolder. 
Example 

The following example calls GetLastError after a series of Addsubcoinponent calls: 

su . AddSubcomponent (" npplug" , . . . ) ; 

su .AddSubcomponent {" /MS/Shared/ctl3d .dll" , . . . ) ; 

su. AddSubcomponent (" =C0MM=/NetHelp /royalp lug/ royalhelp- html" ,-.-); 
err = su. Getl^stError ( ) ; 

GetWinProfile 

(W/indows only) 

Constructs an object for working with a Windows /ml file. 
Method f 

Sof twareUpdate 

Syntax 

WinProfile GetWinProfile ( 
Object folder r 
String file); 

Parameters 

The GetWinProfile method has the following parameters: 

folder An object representing a directory. You create this object by passing a string representing the directory to 

the GetFolder method. 

file A relative pathnair^ to an initiarizatlon file in the directory specified by the folder parameter, such as 
" royal/ royal.ini". 

Returns 

A WinProfile object 
Description 

The GetWinProfile method creates an ol>iect for manipulating the contents of a y^"^^)^ -j-^.^^^^^^ 

have this object, you can call its methods to retrieve strings fi-om the file or to add stnngs to the file. For Information 

on the returned bbiect, see WinProfile. 

This method returns null on Unix and Madntosh platforms. 
Example 

To edit the win . ini file, you would create a WinProfile object v\mh this call: 
su. GetWinProfile ( su. Get Folder ("Windows" ) . "win.ini"); 

GetWinRegistry 

(Windows only) 

Constructs an object for working v\nth the Windows Registry. 
Meth d f 
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SoftwareUpdate 
Syntax 

WinReg GetWinRegistry ( ) ; 

Parameters 

None. 

Returns 

A WinReg object. ^. 
Description 

Th GetWinRegistry method to create an object for manipulating the contents of the VWIndows Registry. Once you 
have this object, you can call its methods to retrieve or change the registr/s content. For Information on the returned 
object, see WinReg. 

This method returns null on Unix and Macintosh platforms. 
Example 

To use the hkeyjusers section of the Windows registry, use these statements: 

su = new netscape, softupdate, SoftwareUpdate (this, "Royal Software"); 

winreg = su. GetWinRegistry (> ; 

winreg . SetRootKey (winreg . HKEY_USERS ) ; 

Patch 

Updates an exiisting component. 
Method of 

Sof twareUp>date 
Syntax 

int Patch ( 

String registryNaine^ 

String jarSourcePath, 

Object localDirSpeCr 

String relativeLocalPath) ; (Communicator 4.3 or later) 

int Patch ( 

String registryNaroe, 
Versionlnfo version. 
String jarSourcePath, 
Object localDirSpec, 

String relativeLocalPath) ; (Communicator 4.5 or later) 

int Patch ( 

String registryName, 
string version^ 
string jarSourcePath, 
Object localDirSpec, 

string relativeLocalPath); (Communicator 4.5 or later) 
Parameters 

The Patch m thod has the following parameters: 



3© 



r eg i s t r y N ame 



The pathname in the Client Version Registry for the component that is to be patched. 



This parameter can be an absolute pathnanne. such as 

/royalairways/RoyalSW/executableor a relative pathname, such as executable. 

Typically, at>solute pathnames are on/y used for shared compon nts, or components that 
come from another vendor, such as /Microsoft/ shared/msvcrt 40.dll. 

Typically, relative pathnames are relative to the main pathname specified in the 
startinstall method. If you want the pathname to be relative to the current 
Communicator installation instead of to the paclcage being installed, use the prefix 
" =?cpMM=/" as the beginning of the pathname. 

If you want the pathname to be relative to the current user folder, use the prefix " =user=/v . 

This parameter can also be null, in which case the jarSourcePath parameter Is used as a 
relative pathname. 

Note that the registry pathname is not the location of the software on the computer, it is the 
location of infomnation about the software inside the Client Version Registry. For Information 
on choosing an appropriate registry name, see "Positioning Software in the Client Version 
Registry- on page 33. 

An versioninf o object containing the version number for the subcomponent. This 
parameter can t)e null. In this case, no version is associated with this component and It is 
always updated. 

A string specifying the location of the differences file within the JAR file. To create the 
differences file, use the NSDif f utility, which is descrit>ed in Appendix D. The NSDiff Utifity." 
An object representing the directory in v^ich the sut>component that is to be patched 
resides. You create this object by passing a string representing the directory to the 
GetFolder method. 

relativeLocalPath A pathname relative to the localDirSpec parameter that Identifies the subcomponent that 
is to be patched. You must always use fon^^rd slashes (/) in this pathnanrte, regardless of the 
convention of ttie underlying operating system. If this paranr>eter Is blank or null, 
jarSourcePath Is used. 

Returns 

An Integer error code. For a list of possible values, see "Return Codes" on page 10Z 
Description 

The Patch method to update an existing component by applying a set of differences between two known versions. 
The set of differences is in gdiff format and Is created by the NSDif f utility. For Information about using NSDif f , 
see Appendix D, The NSDiff Utility.- 

A patch can only t>e appfied between two known versions. If the existing version of the file does not match the 
checksum stored In the gdiff file. Patch returns an error without applying the patch. After Patch appfies a patch, It 
compares a checksum .of the resulting file against a checksum stored in the gdiff file. If the checteums do not 
match, the original version of the file is preserved, the patched version of the file is discarded, and an error code Is 
returned. 

Any single installation process can apply multiple patches to the same file. 

If Finaiizeinstall indicates that a reboot is necessary to complete the Installation, patch may not work In 
subsequent SmartUpdate processes until the rekx>ot Is performed. 

ResetError 

Resets a saved error code to z ro. 

Method f 

S of twa reUpda te 

Syntax 



version 

jarSourcePath 
localDlrSpec 



void ResetError (); (Communicator 4.5 or later) 

Parameters 

None. 

Returns 

Nothing. 

Description 

The ResetError method resets any saved error code to zero. See GetLastError for additional information. 
Example 

To reset the last error code to zero: 
su.ResetErrorO; 

SetPackageFolder 

Sets the default package folder. 

M thod of 

Sot twa r eUpda t:e 

Syntax 

void SetPackageFolder ( 

Object folder); (Communicator 4.5 or later J 

Parameters 

The SetPackageFolder method has the following parameter 

folder An object representing a director/. You create this object by passing a string representing the directory to 
the GetFolder or Get Folder Con^onent method. 

Returns 
Nothing. 
Description 

The SetPackageFolder method to set the defoult package folder that is saved with the root node. When the 
package fokier is set, it is used as the default for forms of Addsubcoroponent and other methods that have an 
oplionallocaXDirSpep parameter. 

You should only call this method once, and you should always call it Immediately after you call startinstall. If you 
call SetPackageFolder multiple times, the last folder set Is the fokier that Is saved in the Cfient Version Registry 
and used as the default for other installations. 

startinstall 

Initializes the installation of the specified software and version. 
Method of 

SoftwareUpdate 
Syntax 

int Startinstall ( 
string package^ 

SI. 
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Versionlnfo version, 

int flags); {Communicator 4.0 or later) 

int Startlnstall ( 
String package. 
String version, 

int flags); (Communicator 4.5 or later) 

int startlnstall ( 
String paclcage. 

String version); (Communicator 4.5 or later) 

Paramet rs ' \ 
The startlnstall method has the following parameters: 

package The Clent Veislon Registry pathname lor the software (for example: Plugins/Adobe/Acrobat or 
/royalairways/RoyalPi/). It is an error to supply a null or empty name. 

The name can be absolute or relative. A relative pathname Is relative to the Communicator namespace. A 
relative pathname must start with plugins/. to be relative to the plug-Ins portion of that namesjraoe or 
j ava/download/, to be relative to the Java portion. All other parts of the Communicator area of the 
registry are resented for use by Netscape. 

The Client Version Registry is a hierarchical description of the software registered for i^e with 
Communicator. The registry name provided here is not the location of the software on the "f chine, it te 
the location of Informatfon about the software Inside the registry. This distincbon is important wtien you 
add components with the Addsubcomponent method. For Information on choosing an appropnate 
registry name, see "Positioning Software In the Cieri Version Regtetry" on page 33. 
version A Versionlnfo object (Communicator 4.0 or latei) or a string (Communicator 4.5 or later). This 
parameter can be nuM. in which case, the software is installed without a version. If you supphr a 
version, future visits to your web page may trigger unnecessary downloads, greatly annoying the user. 

When version Is a Versionlnfo ol)ject, it represents the version of the package In the CBent Version 
Registry. 

When version Is a String, It should be four Integer values delimited by a period representing the 
version number, such as "4.2.1 .1 234". 
f laqs An optional value that modifies the standard behavior of the user Interface: no_status_dlg (to suppress 
the display of the dialog box that asks the user to confirm the Installation) and no_finali ze_dlg (to 
suppress the display of the progress bar during the Finalizeinstall method). The no_status_di^ 
flag is Intended for use by script writers that provide their own user Interface. Both valuesjwn be speafl d 
by performing a bitwise OR operation on them. If you do not spedly the flags parameter, the secunty 
dialog txix and the progress bar are displayed. 

Returns 

An integer error code. For a Bst of possible values, see "Return Codes" on page 10Z 
bescriptibn 

The startlnstall method mitiaozes the Installation of the specified software. You must call flniis method 
immediately after the constructor. It is an error to call any other sof twareupdate methods before calling 

Startlnstall. 

After cainng startlnstall. your script must call Abortlns tall or Finalizeinstall before it finishes. If your 
script does not call Abortlnstall or Finalizeinstall. Communicator virill not be able to ctean up prop rly after 
your script finishes. 

Example 

To start installation for th Royal Ainvays plug-in. you could use this code: 

version = new netscape . sof tupdate .Versionlnfo (3, 2, 1, 0) ; ^ 
su = new netscape, sof tupdate. sof twareupdate (this, "Royal Airways Plug-in ); 
err = su. Startlnstall {" /royalairways/RoyalPI/" , version, 
netscape . sof tupdate . Sof twareupdate . FULL_INSTAI.Ii) ; 
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Uninstall 

Urtnstate a package that was previously installed by a SmartUpdate process. 

Meth dot 

SoftwareUpciat:e 

Syntax 

'"'sStnrpicKlgeNaxne) ; (Con^unlcator 4. 5 or lator) 
Parameters 

The uninstall method has the following parameter. . » ,. ^ 

A suing n,n» .f pad-B. » b. u^ns...... 

Returns 

An integer error code. For a list of possWe values, see "Return Codes- on page 1 02. 

TutnTli method u^nstalls a pacl^gethat^ pr^^^^^^ 
Communt^tir waits until the file Is no longer busy to remove It 

Trigger 

Atiggering script onawet, page usesaTriggero.^ctlndownloa<«ng and instaiong^^^^^^ 
In Package 

netscape . sof tupdate 
Method Sununary 

-^"■""'^7-,„oWec.,.pr«en«n9*.v«*.nn„n*.r»=n,«..0. n, 
, _ Returns aver sionlnfo oDjeci represenuiiy «■ 

Getversioninfo version Registry for the specilied soflware or component. 

CompareVersion 

,„,„^ dow^»-n, and .n«..,.on „.he ^ .he resu^ o, a ve,*n 

comparison. 

Method of 

Trigger 
Syntax 

int Coit¥> a reversion ( 
int CoirqpareVersion ( 



string registryName, 

String version); f Communicator 4.5 or later) 

int CoiqpareVersion ( 
String registryName, 
int major, 
int minor, 
int release, 

int build); ^Communicator 4.3 or later) 



Param ters 

Ttie compareversion method has the following parameters: 

r egistryNaiue The pathname In the crient Version Registry for the component whose version Is to k>e compared. 
This parameter can t>e an absolute pathname, such as 

/royalairways/Royalswor a relative pathname, such as piugsin/royalairway/Royalsw. 

Note that the registry pathname Is not the location of the software on the computer, tt Is the I cation 
of information about the software inside the Client Version Registry, 
version A versioninf o object containing version infomiation or a string In fte format 

major jn/nor,refeaseJbuf/d, where major, minor, refease. and Dw/d^xe integer values representing 
version information. 



Returns 

If the v rsions are the same or if SmartUpdate Is not enabled, this method returns 0. If the version ^^^^^^^^^^j^^ 
Is smaller (earHei) than version, this method returns a negative number. Othenvise. this method returns a posmv 
number. In particular, this method returns one of the following values: 

• -4: registryName has a smaller (earlieO nrtajor number than version. 

• -3: registryName has a snr^aller (earlieO niinor number than version. 

• -2: registryName has a smaller (earfier) release number than version. 

• -1 : registryName has a smaHer (earlier) build number than version. 

• 0: The version numbers are the same; both objects represent the same version. 

• 1 : registryName has a larger (newer) build number than version. 

• 2: registryName has a larger (neweO release numl>erthan version. 

• 3: registryName has a larger (newer) minor number than version. 

• 4: registryName has a larger (newer) major number than version. 

The following constants can be used to check the value returned by conpareVersion: 

int MA0rOR_DIFF = 4; 
int MIn6r_DIFF = 3; 
int REL_DIFF = 2; 
int BLD_DIFF =1; 
int EQUAL = 0; 

In Communicator 4.5. the following constants are defined and available for checking the valufe returned by 

Compareversion: 

Trigger . MAJOR_DIFF 
Trigger . MINOR_DI FF 
Trigger. REL_DIFF 
Trigger . BLD_DIFF 
Trigger . EQUAL 

Description 

Th compareversion method compares the version of a installed file or package with a specified version. 

If registryName is not found in th Client Version Registry or if registryName does not have version, 
registryName is assumed to have a version of 0.0.0.0. 

If registryName represents a file. Compareversion checks for the existence of the file. If the file has be n 
deleted. Its version is assumed to be 0.0.0.0. 



4 orx/xf 



ConditionalSoftwareUpdate 



Initiates the downloading and installation of the specified version of the specified software. 

Meth d f 

Trigger 

Syntax 

Boolean ConditionalSoftwareUpdate ( 
String url. 
String registryName, 
Versionlnfo version, 

int mode) ; (Communicator 4, 0 or later) 

Boolean ConditionalSoftwareUpdate ( 
String url. 
String registryName^ 
String version, 

int mode); (Communicator 4,5 or later) 

Boolean ConditionalSoftwareUpdate ( 
String url. 
String registryName, 

String version); (Communicator 4,5 or later) 

Boolean ConditionalSoftwareUpdate ( 
String url. 
String registryName, 
int diff Level, 
String version, 

int mode); (Communicator 4,5 or later) 
Parameters 

The ConditionalSoftwareUpdate method has the following parameters: 



t 



url 



A uniform resource locator specifying the location of the JAR file containing th software update. 



registrvNameThe pathname in the Client Version Registry for the software that may t>e updat d. The value of 

registryName should match the name passed to the Getversioninf o method of the Trigger 
object and to the Startlnstall method of th Sof twareUpdate object. 
A versionlnfo object containing version information or a string in the format 
m3jarjninorjefeaseJ}uffcf, where major, m/nor, re/ease, and buffdzx^ Integer valu s representing 
version information. 
One of. 



version 



flag 

Trigger . DEFAULT^MDDE 
Trigger - FORCE_^DDE 
Trigger . SILENT_M3DE 

Trigger. FORCE_M)DE I Trigger . SIIiENT_M3DE 
If f lagis missing, Trigger . DEFAULT_MDDE Is assumed. 

For a descrif^on of the effect of the flag parameter, see the startsof twareUpdate method, 
diff Level A constant that indicates sensitivity to differences in versions. A combination of. 

Trigger .MAJOR_DIFF 
Trigger. MINOR_DIFF 
Trigger . REL_DI FF 
Trigger . BLD^DIFF 

For example, if you specify mtwor^diff. the update is triggered only If version Is newer than the 
item in the Client Version registry In the first digit 

If you specify a negative value, the instaU is triggered If version is older than the item in the Client 
Version Registry in the specified digit This is useful when you need to downgrade a component. 
When you specify a negative diff Level, flag must usually be Trigger . FDRCE^MDDE. 

If you do not specify a value for the diff Level parameter, the most sensitive difference level Is 
assumed (Trigger3iJD_DiFE). 

Returns 

False if the update is not necessary; othenAAse. true. A return value of true does not indicate a successful update was 
finished, simply that it started. 

Description 

The conditionaisoftwareupdate method triggers the start of the software update for « I»rt<^«ar versiorjof a 
component The software update starts only If there is not a later version of the software Installed In the Cli nt 
V^Son R^tetry. Contrast thte with the st:artSo£twareUpdate nnethod and the conditionaisoftwareupdate 
nnethod. 

If coiDponentName represents a tile, the disk Is checked for the existence of componentiName. If the file does not 
exist, the installation is triggered. 

Example 

This example triggers an update only if the software isnt already on the machine or If an earlier version Is there: 

version = new netscape.softupdate.VersionInf o (2, 0, 1/ 0) ; 
trigger = netscape, sof tupdate. Trigger; 



if ( trigger .UpdatedEnabledO ) 

trigger . Conditionaisoftwareupdate { 



ince 



..h.tp://royalairways/royalp.g. jar" , " /royalai.ways/RoyalSW" , version, 
trigger. DEFAULT_m:>DE) ; 

GetVersion^nfo 

JSSTnbl trigger Scripts and installation scnpb. 

M thodof 

Trigger 
Syntax 

Versionlnfo GetVersionInf o < ' 
String component) ; 

Parameters 

The Getversioninf o method has one paranneter 
?<:^^»rTh. n«T» of s =«npon». 1" th. Cl«t Ve«to. R«l«nr. 



Returns 

If SmartUpdate Is disabled, this method returns null. 



IT smanupaaie i5» 

method returns null. ^ ^*k^ 

,^,n„, a con^wm. a „^«„.«..n.ica«s,ha..e component s^ouM a.*.,. w^«,«» 

opportunity arises. 
Example 

™s cod. us»*. ««e„i=nlnt. m-ho.. » d.«n*» wN* OAR ...te 

"plugins/royalairways/RoyalSW" ) ; 

if (installed_version = null I < q ) 

trigger -DEFWn.T_hDDE) ; 
// If the installed version is 3 . 0, /^f^" 

"^^^rt?;;//^s;^o^y-a^A^^^^^ 

"plugins/royalairways/RoyalSW , vj_^, t^c 

StartSoftwareUpdate 

Triggers the downloading and Installation of the software at the specified URL. 
M thod of 



Trigger 
Syntax 

Boolean StartSoftwareUpdate ( 
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string url^ 

int flag); (Coinmunicator 4.0 or later) 

Boolean StartSof twareUpdate ( 

String url) ; (Coinmunicator 4.5 or later) 



Parameters 

The StartSof twareUpdate method has the following parameters: 

url A uniform resource locator specifying the location of the JAR file containing the software. 



flag One of. 



Trigger . DE FAULT JM3DE 
Trigger . FORCE_hDDE 
Trigger . SILENTJMDDE 

Trigger. FORCE_M3DE I Trigger .8 ILENT__MDDE 
Trigger. FORCE_MDDE 1 Trigger •SII£NT_MDDE 
If flag Is missing. Trigger. default_mdde Is assumed. 
The flag parameter Is described In detail below. 



Returns 



True. 



Description 

The StartSof twareUpdate method triggers a software update without first checking to see If a later version of the 
package exists. Contrast this with the conditionaisof twareUpdate method. 

The flag parameter specifies information to pass to the InstaUation script. There are two flags you can pass. 
Trigger. FORCE_M>DE and Trigger • SILENT_M0DE. 

Passing the Trigger . FORCE mdde flag requests that an Installation be allowed to override a more recent version of 
a component A trigger script ^an use this flag to request a component be downgraded. "^Tri^er •^J^^-j^^'if 
included, a more recent version of a component can be overridden. It it Is not included a ^"^""^l^J^^l^ 
Sere is no previously installed version or if the installed version number is null or smaller than the specified version. 

For the request to be complied with, in the corresponding Installation script, all calls to the sof twareUpdate o« cts 
Addsubcoitiponent method must pass this . force as their last parameter, this . force reffeds the value of th 
Trigger . PORCE_MDDE flag. 

The Trigger . SILENT MDDE flag requests a silent Installation, If this flag Is Induded. the progress and pernriission 
dialog box may not appi^ar while the software is being downloaded and installed. Once ^Sain foi^^^^^ be 
comSed with, the co\?^ponding installation script must obey the request. The -Trigger . s ILEOT^^ 
indicated in the Installation script by the value of this . silent. If this . silent is true, the mstaUatlon scnpl should 
suppress the display of dialog boxes. 

In addition, a silent installation can occur only If the signer of the JAR file has the silentinstall privilege. This 
privilege can t>e set only using Netscape Mission Control. 

The siLENT_hK>DE flag never suppresses the appearance of security dialog boxes. 
Example 

The following cod uses the startsof twareUpdate method to unconditionally trigger a download from 
http : / /royalairways/ royalpkg .jar as long as SmartUpdate Is enabled on the browser: 



trigger = netscape, sof tupdate. Trigger; 
if ( trigger .UpdatedEnabledO ) 
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trigger . S tartSof twareUpdate ( 

"http://royalairways/royalpkgoar" , trigger .DEFAULT_KDDE) ; 

UpdateEnabled 

Indicates whether or not the JAR Installation Manager is enabled for this client machine. 
Method f 
Trigger 
Syntax . 

Boolean UpdateEnabled (); (Communicator 4.0 or later) 

Parameters 

None 

Returns 

True if SmartUpdate is enabled for this client machine; othenwise, false. The nnethod reflects the value of th 
autoupda te - enabled preference. 

Exantple 

The following code uses the s tarts of twareUpdate method to unconditionally trigger a download from 
http://royalairways/royalp)cg.jaras long as SnnartUpdate is enabled on the browser 

trigger = netscape . softupdate . Trigger; 
if { trigger.UpdatedEnabledO ) 
trigger . StartSof twareUpdate ( 

•rhttp://royalairways/royalpkg. jar" , trigger . DEFAULT__MODE ) ; 

Versionlnfo 

You use versionlnfo objects to contain version information for software. This object and its methods ar used 
both when triggering a download, to see whether a particular version needs to be Installed, and when Ir^talBng the 
software. 

In Package 

netscape • softupdate 
Method Summary 

Versionlnfo Creates a Versionlnfo object. 

coinpareTo Compares the version inforroaition specified in this object to the version information specified in the 
version parameter 

Versionlnfo 

Creates a Versionlnfo object 

Method of 

Versionlnfo 

Syntax 

Versionlnfo ( 
int maj^ 
int min, 
int rev, 

int bid); (Communicator 4.0 or later) 

to 



Versionlnf o ( i *- \ • 

String version); (Communicator 4 . 5 or later)- 

Parameters 

The versionlnf o constructor has the following parameters: 
ma j The major version numt>er . 

min Minor version number. 

• rev Revision number. 

bid BuiW numt)er. 

version A string representing version information in the format "4.1 ^.1234". This parameter is availabie in 
Communicator 4.5 or later. 

When mai. min. rev. and trfd are provided as parameters, all four parameters are required, but ail of them can be 

zero. 

Returns 

A new Versionlnf o object. 
Example 

This code constructs a versionlnfo object forthe 3.2.1 version of the Royai Ai«.ays plug-4n using the integer fom,: 
version = new netscape. softupdate .Versionlnfo (3, 2, 1, 0) ; 

This code constructs a versionlnfo object for the 3.2.1 version of the Royai Ain^ays piug-ln usir^g the string fom,: 

version = new netscape . softupdate .Versionlnfo (" 3 .2 . 1" ) ; 

compareTo 

compares the ve,sion infom^tlon specified in tWs object to the veision information specified in the version 
parameter. 

Method of 

Versionlnfo 

Syntax 

^"^^ersionlnfo version) ; {Communicator 4.0 or later) 

coropareTo ( ^ c -i 

String version); (Communicator 4.5 or later; 

compareTo ( 
int major, 
int minor, 
int release, 

int build); (Communicator 4.5 or laterj 
Parameters 

The compareTo m thod has the following parameters: 
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ence 



ma j The major version number, 

min Minor version number, 

rev Revision number, 

bid BuiW number. 



format "4.1 .2.1234" (Communicator 4.5 or latei). 



Returns 

l!S!rSrtcutar. this method returns one of the following values: 

^- This version obiect has a smaHer (earlier) major number than version. 
Z- ThS veSlon ob ect has a smaller (earUeO minor number than version. 
-2 Thte ^eS on ob ect has a smaller (earlier) release number than ver sxon. 
1 • Thte version olject has a smaller (earlieO build number than version, 
i T?e viSn nSXrs are the same, both objects repr^ent the same version. 
?• TOs^eS otjert has a larger (newei) build number than version. 

2- This ^eSon object has a larger (neweO release number than ver sion. 

3- iSis version ob ect has a larger (newer) minor number than version. 
4: Thfe Version object has a larger (neweO major number than version. 

The following oonstanis can be used to check the value returned by cotnpareversion: 

int MAJORj:>IFF = 4; 
int MINORJ>IFF = 3; 
int REL_DIFF = 2; 
int BliD__DIFF = 1; 
int EQUAL = 0; 

,„ Con«^tea». 4.5, .oUow.no cons«* ar. d,.n«. av«,a«e cheddn, th. valu. r«um«l 

coic?)areTo: 

Vers ioninf o , MAJOR_DI FF 
VersionInfo.MINOR_DIFF 
Versionlnf o . REL._DIFF 
Versioninf o . BLD_DIFF 
Versionlnf o • EQUAL 

Example 

eo., us««.e co„^«.Ton«»«<. .0 datem-n. whothar or ootva,s.cn 3^., o,«,a Ro,a, «,v.a,sso«»». has 
been previously Installed: 

if ( existingVI.coropareTo(neWVI) <= 0 ) { 
// proceed to update ... 

1 

WinProfile 

(V^ndows only) 
SoftwareUpdate object 

£2- 



In Package 

netscape . sof tupdate 
Meth d Summary 

getstring Retrieves a value from a . inifile. 
writestring Changes a value In a . inifile. 

getstring 

Retrieves a value from a . inifile.* 

Meth dof 

WinProfile 

Syntax 

string getstring ( 
String section. 
String key) ; 

Parameters 

The method has the following parameters: 
section Section In the file, such as "boot" or " drivers". 

key The key in that section whose value to return. 
Returns 

The value of the key or an ennpty string if none was found. 
Description 

The getstring method is similar to the Windows API function GetPrivateProf ilestring. UnRke that function, 
this method does not support using a null key to return a list of keys in a section. 

Example 

To get the nanr>e of the wallpaper file from the desktop section of the win . ini tile, use tNs call: 

ini = su.GetWinProfile ( su. Get Folder ("Windows" ) , "win. ini" ); 
ini . getstring (" Desktop" , " Wallpaper" ) ; 

writeString 

Changes a value In a . inifile. 

Meth dof 

WinProfile 

Syntax 

Boolean writeString ( 
String section. 
String key. 
String value); 

Parameters 

The nnethod has the following parameters: 



terence 



section Section In the file, such as " boot" or " drivers" 
key The key in that section whose value to change, 
value The new value. 



Returns 

True if successfully scheduled, othenwise, false. 
Description 

method does not support using a null key to delete an entore section. 
Valu s are not actually written until Finalizeinstall Is called. 
Example 

To set the name of the wallpaper file from the desktop section of the win . ini file, use this call. 

ini = su.GetWinProfile (su.GetFolder ("Windows" ), "win ini" ) ; 
ini.writestring ("Desktop", "Wallpaper", "newpathname ), 

WinReg 

(VNAndows only) 

Sof twareUpdate object 

This discussion assumes you are already familiar with the Windows Registry. For information on it. see API 
documentation for Windows NT or Windows 95. 

v*.n you a ^^^-^^^j'^ ^^sxi-s^^^S;^^:^:^'^^:^ 

getValue and setValue methods. 

Reading regist^^ values Is immediate. However, writing to the registry is delayed until Finalizeinstall Is called. 
In Paclcage 

netscape . sof tupdate 

Method Summary 

createKey Adds a key, 

deleteKey Removes a key. 

deletevalue Removes the value of an arl>itrary key. 

getvalue Retrieves the value of an arlMtraiy key. 

getvalues tr ing Retrieves the value of a key, when that value Is a string. 

setRootKey Changes the root key being accessed. 

setvaiue Sets the value of an artJitrary key. 

setvaiues tring Sets the value of a key, when that valu Is a string 

creat Key 

Adds a key to the registry. 



Meth dof 

WinReg 
Syntax 

int createKey ( 
String subkey. 
String classname); 

Parameters 

The method has the following parameters: 

subkey The key path to the appropriate location In the key hierarchy, such as 

••Software\\Netscape\\Navigator\\^4ail". 
classname Usually an empty string. For information on this parameter, see the description of RegcreateKeyEx in 

your Windows API documentation. 

R turns 

0 if It succeeded; a nonzero number if it failed to schedule the creation. For a list of possible values, see "Return 
Codes" on page 102. 

Description 

The createKey method adds a key to the registry. You must add a key to the registry before you can add a valu for 
that key. 

deleteKey 

Removes a key from the registry. 

Method of 

WinReg 

Syntax 

int deleteKey ( 
String subkey) ; 

Paranneters 

Th method has the following parameters: 

subkey The key path to the appropriate location in the key hierarchy, such as 
Sof tware\\Netscape\\Navigator\\Mail". 

Returns 

0 if it succeeded; a nonzero number if It failed to schedule the deletion. For a list of possible values, see "Return 
Codes" on page 102. 

del teValue 

Removes the value of an arbitrary key. 

Method of 

WinReg 

Syntax 

int deleteValue ( 
String subkey. 
String valname) ; 
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Parameters 

The deletevalue method has the following parameters: 
subkey The key path to the appropriate location In the key hierarchy, 

" Software\\Netscape\\Navigator\\Mail". 

valname The name of the value-name/value pair you want to remove. 



R turns 

0 if it succeeded; a nonzero number if It failed to schedule the deletion. 

g tValue 

Retrieves the value of an arbitrary key. 

Meth dof 

WinReg 

Syntax 

WinRegValue getValue ( 
St.ring subkey, 
S tiring valname) ; 

Parameters 

The getValue method has the following paranr^eters: 

subkey The key path to the appropriate location in the key hierarchy, such as 

" softwareWNetscapeWNavigatiorWMail". 
valname The name of the value-name/value pair whose value you want. 



Returns 

A winRegValue obiect representing the value of the named valueniame/value pair or null If there Is no value or If 
there is an error. See winRegValue for inforrnation about these values. 

Description 

The getvalue method retrieves the value of an arbltraty Icey. Use mis method If the value you want is not a string. If 
the value is a string, the getvaluestring method is more convenient 

getValueString 

Retrieves the value of a key, when that value is a string. 

M th dof 

WinReg 

Syntax 

string getValueString { 
string siibkey. 
String valname) ; 

Paranieters 

Th getValueString method has the following parameters: 

subkey Thekeypathtotheappropriat location in the key hierarchy, such as 

••SoftwareWNetscapeWNavigatorWMail". 
valname The name of the value-name/value pair whose value you want. 



R turns 

A string representing the value of the named value-nanne/value pair or null if there's an error, the value is not found, 
or the value is not a string. 

Description 

The getvaluestring method gets the value of a string. If the value is not a string, use the getvalue method 
instead. 

setRootKey 

Changes the root key being accessed. 

Meth dot 

WinReg 

Syntax 

void setRootKey ( 
int key) ; 

Parameters 

The method has the following parameter: 
key An Integer representing a root key in the registry. 

Returns 
Nothing. 
Description 

The setRootKey changes the root key. When you create a winReg object, it is set J^^^^^^^^^ 
HKEY_CLASSES^ROOT portion of the registiy. If you want to access keys in another portion, you must use this 
method to change the root key. 

on 16-bjt Windows platforms. hkey_ciasses_root is the only valid value and this method does nothing. 
These root keys are represented as fleWs of the winReg object. The values you can use are: 

• HKEY_CLASSES__ROOT 

• HKEY_CURRENTJUSER 

• HKEY_IiOCAIi_MACHINE 

• HKEY JUSERS 

Example 

To use the hkeyjusers section, use these statenr>ents: 

su = new netscape. softupdate.SoftwareUpdate (this, "Royal Software"); 

winreg = su. GetWinRegistry { ) ; 

winreg . SetRootKey {winreg . HKEYJUSERS ) ; 

s tValue 

Sets the value of an arbitrary key. 
Method of 

WinReg 



Syntax 



string setValue { 
String subkey, 
string valname, 
WinRegValue value); 

Parameters 

Th setvalue method has the following parameters: 

subkey The key path to the appropriate location in the key hierarchy, such as 

"Software\\Netscape\\Navigator\\Mail". 

valname The nanne of the value-name/vaiue pair whose viilue you want to change. ^ . 

value A WinRegValue Object representing the new non-string value. See winRegValue for information about 
these values. 

Returns 

0 if It succeeded; a nonzero number If it failed to schedule the action. For a list of possible values, see -Return 
Codes" on page 10Z 

Description 

The setvalue method sets the value of an arbitrary key. Use this method if the value you want to set is not a string. 
If the value is a string, the setvaluestring method Is more convenient 

setValueString 

Sets the value of a key, when that value Is a string. 

Mettled of 

WinReg 

Syntax 

int setvaluestring ( 
string subkey^ 
String valneune. 
String value) ; 

Parameters 

The method has the following parameters: 

subkey The key path to the appropriate location In the key hierarchy, such as 

Sof twareW NetscapeW NavigatorW Mail", 
valname The name of the value-name/value pair whose value you want to change. 

value The new string value. 
Returns 

0 if it succeeded; a nonzero number if it failed to schedule the action. For a list of possible values, see "Return 
Codes" on page 102. 

D scription 

The setvaluestring method sets the value of a key when that value is a string. Use this method if the value you 
want to set is a string. If the value is not a string, us the setvalue method instead. 

WinR gValue 

(VNAndows only) 



Advanced \AAndows developers can use this object to manipulate non-string values for the V^ndows Registry. An 

thic ^rThs^^^^ tvue of the data and the value. For information on the possible data types for a 

^e^CvSue^'Se y^u^^nSl^^^^ You suppty the value for these fields to the constructor forthis 

Class. 

In Package 

netscape . sof tupdate 

WinRegValue 

\ 

Creates a winRegValue object. 
Syntax 

WinRegValue ( 

int datatype, 
byte( ] regdata); 

Parameters 

The WinRegValue constructor takes the fonowing parameter: 

datatype An integer Indicating the type of the data encapsulated by this object. The possible values are: 

• WinRegValue.REG_SZ= 1 

• WinRegValue . REG_EXPAND__S2 = 2 

• WinRegValue . REG_BINARY = 3 

• WinRegValue .REG_DWORD = 4 

• WinRegValue . REG_DWORD_LITTLE_ENDIAN = 4 

• WinRegValue . REGJDWORD_BIG_ENDIAN « 5 

• WinRegValue . REG_LINK =6 

• WinRegValue . REG_MUIiTI_SZ = 7 

• WinRegValue . REG_RESOURCE_LIST = 8 

• WinRegValue . REG_FUI.Ii_RESOURCE_DESCRIPTOR = 9 

• WinRegValue . REG_RES01JRCE_REQXJIREMENTS_LIST = 10 

regdata A Java byte array containing the data. 
Returns 

A new WinRegValue object, with the data members type and data set to the values passed to this constnjctor. 

Return Codes 

The methods described In this chapter can return any of the following return codes. In Conrununlcator 4.5. thes 
constants are defined as part of the SotlwareUpdate object 



Name | 


Code 1 


Explanation 1 


SUCCESS 1 


0 1 


Success. 1 


REBOOT_NE EDED 


... 

999 


The files were Installed, but one or more components were in us 
Restart the computer and Conrwnunlcator to complete the installation 
process. 

On Windows NT. you may only need to restart Commuinicator as long 
as you did not replace operating system tiles. 


BAD_PACKAGE_NAME 


1-200 

i 


A probi m occurred with the package name supplied to 

Startlnstall 


tJNEXPECTED_ERROR 


1-201 

i 
1 

IT 


1 An unr cognized rror occuaed. 

i 1 
si '• ■ 1 

ir 



ACCESS DENIED p -2Q2 | 1 

ii 


rhe user did not grant the required security privilege. | 


TOO MANY CERTIFICATES ll -203 | 1 

1! ! 


nstellation script was signed by more than one certilicate j 


NO_INSTAI*liER_jCERTIFICATE j| -204 j 1 


, 1 

nstallation script was not signed | 


NO__CERTIFICATE | - 


205 r 

1 


Extracted file is not signed or the file (and. therefor . its c rtmcate) 
could not t>e found. 


NO_MATCHING_CERTIFICATE | - 

> „ 


206 


Extracted file was not signed by the certificate used to sign the 
installation script 


UNKNOWN^ JAR_FI I-E 

1 


•207 


JAR file has not been opened 


INVALID_7\RGUMENTS 

1 

-L 


-208 ' 


Bad parameters to a function | 


ILLEGAI*_REIiATIVE_PATH j 


-209 


Illegal relative path | 


i USERjCANCELIiED j 


-210 1 

! 


User clicked Cancel on Install dialog | 


INS TALL JNOT_STARTED 


-211 1 

1 


A problem occun-ed with the parameteis to start:install, or 
star tins tall was not called first 


SILENT_M3DE_pENIED 


-212 1 


The silent Installation privilege has not been granted. 


N0_SUCH_COMPONENT j -21 3 

ll 


1 The specified component Is not present in the Client Version 
I Registry. 


FILE_pOES^«KDT JEXIST jj -21 4 


j The specified file cannot be deleted because it does not exist. 


FILE_RE7\DJ0NLY H -21 5 


The specified file cannot be deleted because its permissions are s t 
to read only. 1 


FILE_IS_DIRECTORY 


(-216 


The specified file cannot be deleted because It Is a directory. j 


NETWORK_FILE_I S_IN_USE 


i -217 


The specified file cannot be deleted because it Is in use. 


APPLE_SI NGLE_ERR 


1 -218 


1 An emjr occurred when unpacking a file in AppleSingle tbrmat. 


INVALI D__PATH_ERR 


p219 

J ,. . 


j The path provided to oetFolder was inyafid. 

i 


PATCH_BADJDI FF 


-220 


An error occurred in GDIFF. 


PATCH BAD^CHECKSSUMJTARGEl 


• -221 


1 The checksum generated for the source file does not matcn me 
checksum In the JAR tile. 


PATCH_BAD_CHECKSUM_RESULT 


1-222 


1 The checksum of the patched file failed. 


UNINSTALL^FAILED 


|-223 

i 


\ An error occurred while uninstalling a package. 

1 
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Appendix A 
Sample Installation Script 

This appendix contains a sample template for a JavaScript-based Installation using the SmartUpdate technology. 

This is the installation script used tor the Netcaster component of Communicator. It is a good template for you to start 
with for your own Installation. 

// First some functions to use in the installation - 

// Used only for debugging when execution needs to be 
// slowed down to follow the output to the Java Console, 
function delay (amount) { 

if ( (debugOutput) && (amount > 0) ) 

var time = new^DateO; 

var seconds = time, get Seconds () ; 

var startCount = 80; 

var newSeconds =70; 

StartCount = (seconds + amount ) % 60; 
time = new Date ( ) ; 
newSeconds ~ time, get Seconds () ; 
while (newSeconds != startCount ) ( 

time = new Date ( ) ; 

newSeconds = time . getSeconds ( ) ; 

) 

} 

) 

// Conditionally displays a message only when debugging, 
function dbglfMsg (condition, message) { 
if (debugOutput condition) 

j ava . lang . System. out . println (message) ; 

) 

// Displays a message only when debugging, 
function dbgMsg (message) { 
i f ( debugOutput ) 

java. lang. System, out. println (message) ; 

1 

// Pops an alert window only when NOT installing in silent mode, 
function cAlert (message) { 
if ( I this . silent) 
alert (message) ; 

1 

// Checks OS and version information, 
function checkSystemEnvironment ( ) { 
var err =0; 

i f ( debugOutput ) { , 
registry_vi = netscape .softupdate -Trigger .GetVersionlnfo ("Netcaster' ); 

dbgIfMsg( (registry_vi == null ), "Warning: No registry info for Netcaster node"! 
if (registry_yi != null) { 

dbgXfMsg( (vi . con^areTo ( regis try_vi) <= 0) , 

"Warning: Version is no newer than previously installed version. ); 

) 

) 



impte installation ^cnpt 



dbgMsgrThe value of navigator .platform is: " + navigator .platform) ; 
if (navigator. platform != •■Win32") { 
err = -20; // wrong OS 

dbgMsg ("Error : Wrong operating system!"); 

cAlertC Error: Wrong operating system: " + navigator. platform) ; 
return err; 

) 

return err; 

} 

^SglISsg( terr != 0), "Error Adding Subcomponent " + fName + "error value: + err), 

if(err != 0) { 

newSubFailure = true; 

1 

delay (FileDelayTime) ; 

) 

// This prepares the specific files to be installed, 
function setupFiles (su) { 
var err = 0; 

if (su == null) { 

dbgMsg ("Error passing su to setupFiles: + err) ; 

return -1; 

) 



err = su. Startlns tall ("Netcaster" , // Package name 

vi f 

netscape . sof tupdate . Sof twareUpdate . FULL^INSTALL) ; 

if (err !=0) { 

dbgMsg ("Error at startlnstall: " + err); 
return err; 

} 

// Get folders, 

CommFolder = su.GetFolder (" Communicator" ) ; 
if (CommFolder nxai) { 

dbgMsg ("ERROR GETTING FOLDER: Communicator"); 

return -1; 

JClassFolder = su . GetFolder (" Netscape Java Classes"); 
if (JClassFolder = null) ( „ x . 

dbgMsg (" ERROR GETTING FOLDER: Netscape Java Classes ). 

return -1; 

HelpFolder = su. GetFolder (" PrograitT ) ; 
if (HelpFolder == null) { 

dbgMsg (" ERROR GETTING FOLDER: Program"); 

return -1; 

} 

// Add subcomponents. 

// Netcaster files ^, ^ • x. 

newsub("", "admin, jar", vi, CommFolder, " Netcast/admxn . ^ar- ) , 

newsub "" "ncjavalO.jar", vi, CommFolder, " Netcast/ncDayalO . ) , 

newsub "" "ncjslO.jar", vi, CommFolder, " Netcast/ncjslO oar- ) , 

newsub("", "addc.htirf', vi, CommFolder, "^etcast/addchtm ), 

newsub!"" , " images/blank. gir', vi, CommFolder, " Netcast/xmages /blank. gxf ) . 

// ... more files . . . 

>; 

newsub rLS^lo' jar", " aavaClasses/»arin^lO . jar" , vi, JClassFolder, "mari^blO . jar" 1 



// Netcaster Help files 

newSub("=C»MM=/NetHelp/Netscape/netcastr/help.hpf" , " Help/help. hp f*' , vi, He.* 

newSub (" =COMM=/NetHelp/Netscape/netcastr/net . htm" , " Help/net . htm" , vi , He! 

newSub {"=CX>MM=/NetHelp/Netscape/netcastr/netHdr . htm" , " Help/netHdr . htm" ^ vi. He: 

newSub (" =CX>MM=/NetHelp/Netscape/netcastr/netcastr . gif" , " Help/netcastr . gif" , vi. He! 
newSub("", "nc_startup.html", vi, HelpFolder, " Ne tea st/nc_s tar tup .html" ) ; 

// If any subcomponent failed, the installation aborts here, 
if (newSubFailure) { 

dbgMsg (" Error adding at least one subcon^onent ) ; 

abortMe ( ) ; 

) *. 

return 0; 

} 

// Handles catastrophic errors, 
function abortMe (err) { 
if ( iabortCalled) { 

dbgMsg ("Install Aborted." + err) ; 

cAlert ("Install Aborted." + err); 

su. Abort Ins tall ( ) ; 

abort Called = true; 

) 

) 

// End of functions. 

// ==================== START ACTUAL INSTALLATION ============== 

// 

// Global variable declarations 

// 

var updateObjectName = "Netscape Netcaster vl.O Install"; 
var versibnMaj = 4; 
var versionMin = 0; 
var versionRel = 4; 
var versionBld = 97139; 

var FileDelayTime = 0; // Number of seconds delay between subcomponents when debugging 

var abortCalled = false; 
var newSubFailure = false; 

var debugOutput = true; // Turns debugging output on/off 

var vi = new netscape, softupdate .Versionlnfo (versionMaj , versionMin, versionRel, versi< 
dbgIfMsg( (vi == null), "Warning: Unable to create the Versionlnfo object."); 

var su = new netscape, softupdate . So ftwareUpdate ( this, updateObjectName ); 

dbgIfMsg< (su == null), "Warning: Unable to create the Sof twareUpdate object,"); 

// 

// Here starts the main body of execution. 

// 

java.lang.System.out.println{" Starting script. . •" ) ; 

var err = 0; 

if ( (su null) ) { 

dbgMsg ("new So ftwareUpdate succeeded."); 
err = checkSystemEnvironment ( ) ; 
if { err = 0 ) { 

dbgMsg (" checkSystemEnvi moment succeeded." ) ; 
err ~ setup Files (su) ; 
if (err — 0) { 

dbgMsg (" setupFiles succeeded." ) ; 

err = su . Finalizelnstall { ) ; // This actually copies all the files, 

if (err = 0) { 

cAlert (" Install Complete: Relaunch the Navigator to enable 

Netcaster menu selection."); 
cAlert (" Install Successfully Coital e ted" ) ; 
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} 

else { 

dbgMsg("Error at Finalizelnstall : " + err) ; 
abortMe (err) ; 
) //Finalizelnstall 

} 

else { 

dbgMsg(" Error at setupFiles: " + err) ; 
abortMe (err) ; 
) //setupFiles 

) 

else { 

dbgMsg(" Error at checkSysteihEnvironment: " + err) ; 
eJDortMe{err) ; 
) //checkSystemEnvironment 
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Appendix B 
End Us r Problenis 

^cSne^lS aSnal Information about resolving SmartUpdate end user problems, see 
http.//help.netecape.coni/kb/netcenter/971023-6.html. 

Communicator Prompts to Save JAR as an .exe File 

Caus - The user has attempted to directly download a JAR archive and Is accessing the software through a proxy. 
That proxy has assigned an Incorrect MIME type to a JAR archive. 

any downloaded file (other than an HTML file) as a JAR archive. 

To woric around the problem, the user can save the file to the disk, give it a . j arextension. and open it locally In 
Communicator. 

C mmunlcator Displays the Message: Downloaded file Is not a JAR archive 
Cause There are several possible causes of this error 

. TT,e file that SmartUpdate got from the server was not a JAR archive -Rie sen/er might have returned an HTML 
error message (for example. If It is too busy, or the file was not available). 

. The server is misconfigured. and is sewing JAR archives with the wronig MIME type. 
. The user is accessing the file through a proxy, and the proxy Is misconfigured for the MIME type of JAR 
archives. 

FixAfvoricaround: There are also several possible fixes and workarounds: 
. Make sure that the file is available on the server . 

. Make sure that the sender Is configured properly. (RIes with the . jarextension should be served as 

application/ j ava-archive.) 
. The user can save the file to a tocal disk (with a suffix of . ja^ and open It inside Communicator. 
. The developer can make sure that the MIME type of the JAR archive Is propagated correctly by senrtng files off 

an HTTP server rather than an FTP sender. 

HTML file) as a JAR archive. 
C mmunlcator Displays the Message: SmartUpdate failed: JAR archive failed a security check. 

problems Include: 

• The JAR archive was corrupted during download. 

. The certificate authority the developer us ^ to sign the archive is not recog^^^ 

exarnpl if the developer used a companys certificate server to get the signing certificates, outside users 
probably' will not trust that Certificate Authority. 

• Navigator's security database is corrupted. 
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Fix/w rkar und: You have several options to try to fix the problem: 

• Try downloading the file again 

. Before starting SmartUpdate. show the user how to obtain your certificate authority. Or sign your code with a 
certificate issued by one of the built-in certificate authorities, such as VenSign. 

• Reinitialize your security database. Reinitializing the security database Is an extremely high-risk operation. Do 
not do it unless you're certain its necessary. 



Table of Contents | Previous | Next | Index 



Last L^fdatod: 03/11^99 if:3Z:22 



Tabic of Contents | Previous | Next | Index 

SmartUpdate Developer's Guide 

Appendix C 
R leas Notes 

This appendix contains release notes for SmartUpdate technology In Conr^municator 4.5. 

• New Methods 

The following changes have been made to the SoflwareUpdate class: 

• AddDirectory (new method) (available in Communicator 4.05 and later, but not In Communicator 4.0 through 
4.04) 

• Addsiibcon^onent (new forms to simplify script writing) 

• DeleteFile (new method) 

• DeleteCoinponent (new method) 

• Execute (overloaded fomi that allows convnand-llne arguments on Windows and Unbc systems) 

• GetFolder (new forms that allow the specification of subdirectories) 

• Get component Folder (new forms that allow the specification of subdirectories) 

• GetFolder (new targets) 

• DiskSpaceAvailcible (new method) 

• GetLastError (new method) 

• Patch (new method, supported by a new tool, nsdlfl) 

• ResetError (new method) 

• SetPackageFolder (new method) 

• startlnstall (security privilege changes and new modes) 

• uninstall (new method) 

The following changes have been made to the Trigger class: 

• Coit^areVersibn (new method) 

• Difference level constants added from the Verslonlnfo class 

• startsof twareupdate (mode parameter is now optionaO 

• conditionaisof twareupdate (new forms to simplify checking for version differences) 

The following changes have been made to the Versionlnfo class: 

• Definition for difference level constants 

• The Versionlnfo constructor now takes a single string of the form -4.0^.1234" In addition to the fonm that 
requires lour integers. 

• con^areTo now allows script writers to compare versions without having to create a Versionlnfo object. 

• Security Privileg Changes 
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Prior to Communicator 4.5. the startinstall method could be called with a permission 
parameter that could be full_install or limited_install. In addition, the 
sof twareinstali. silentinstall, and Uninstall security privileges were defined as part of 
the SoftwareUpdate class. 

Communicator 4.5 provides a forni of startinstall that eliminates the permission parameter. 
\A/hen you use this form of startinstall. It assumes FULL_iNSTALrx For backward compatibility, 
LIMITED_INSTALL can Still be used with the startinstall method, but you are encouraged to 
use the new form of startinstall that does not require a permission parameter. 

In Communicator 4.5,softwareinstall.siientlnstall, and uninstairare nonnal, security 
privileges defined In the Security Manager. With this change, any Java or JavaScript can requwt 
these privileges and bring up the security dialog box. This may be useful for web pages to get the 
privilege approved before the download. 

If a trigger script requests silent__mode and Communicator is not configured to support 
siLENTj^ODE, Communicator 4.5 displays the standard secifftty dialog box instead of the "Silent 
Install" security dialog box. This behavior is In contrast to previous versions of Communicator that 
displayed the "SilentJnstair dialog box in this circumstance. 

Obtaining sof twarelnstall privilege includes a grant of standardRegistryAccess so that 
items can be placed in the Shared or Private areas of the Client Version Registry for use by the 
application. If items are place in the Private area of the registry, the install script must be signed by 
the same certificate as the class tfiat vwll eventually read from the registry. 

Obtaining sof twarelnstall privilege also grants the UniversalPref erencesRead privilege, 
but It does not grant the UniversalPref erenceswrite privilege. Script writers who need 
UniversalPref emceswrite privilege must ask for that privilege on their own. 

Obtaining silentins tall privilege automatically grants sof twarelnstall privilege and all of Its 
sub-privileges. 

• Signed JavaScript 

In Communicator 4.5. SmartUpdate installation scripts are signed JavaScript progranns that can use 
features that are available to any signed JavaScript program. 

• Multiple Downloads 

Communicator 4.5 queues triggered installations to prevent multiple downloads that could 
overv4)elm the networtc and any particular computer. Multiple installatons are dovmloaded and 
perfonmed in the order in which they were triggered. 

• Security Policy 

The JavaScript navigator object has a new, read-only securityPolicy property that is a string 
describing the security policy of the running Communicator or Navigator executable. 

« Registry Nodes 

All SoftwareUpdate methods that take a registry name as a parameter can take regte^ 
that begin with " ==user=/" to refer to items registered under the current user. Methods that take a 
registry name as a parameter do not prepend the package registry name. 
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Appendix D 
The NSDiff Utility 

This appendix describes the NSDif f utility, which you use to create a file containing the differences between an 
existing component and an update of that component You use the differences file for the purposes of using the 
Patch method of the sof twareUpdate object 

The NSDiff utiBty can be downloaded from http://devedge.netscape.conn/software/tools/SmartUpdate.htmL Ther 
are versions of the utility for Windows 95/98/NT, Mac OS. and the Unix operating system. 

The syntax for the NSDlf f utilllity is as follows: 

NSDiff [-bA-J [-OA-] [-d| [-wb-] -o^^ filename'^ oldflle newflle 
The command line options for the NSDiff utiHty are listed below: 

-a Specifies that oldrile and newfUe are In AppleSingle format (Mac OS version only) 

-bA- Specifies in bytes the block size to use for the comparison. The default block size is 64. The 

minimum block size is 9. A smaller block size nnay result In a snr^ller differences file that tak s less 
time to download but nnore time to apply. A larger block size may result in a larger differences file 
that takes more tinne to download but takes takes less time to apply. 

-ox Specifies the checksum type. The default checksum type is CRC-32, which is the only supported 

checksum type at this time. 

-d Causes NSDi f f to display diagnostic Infomr^tion while it executes. 

-o" f'liename'* Specifies the name of the differences file. The default is 
nehrfJJename . gdf 

-wb- Improves processing time by turning off special handling for \AAndows executables that have k>een 

processed by 

Bindimage. (NAAndows 95/98/IMT version only.) 
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